Bỏ qua tới nội dung
Ông T.vn

Sandcastle: chạy AI coding agent trong sandbox bằng TypeScript — hướng dẫn cài đặt và dùng

10 phút đọcCập nhật

Bài này là một góc nhìn khác về mattpocock/sandcastle — repo từng đổi tên nên mình viết lại với cách tiếp cận khác. Bài hướng dẫn chính: Sandcastle: chạy AI coding agent trong sandbox bằng TypeScript — hướng dẫn cài đặt và dùng →

Sandcastle: chạy AI coding agent trong sandbox bằng TypeScript — hướng dẫn cài đặt và dùng

Tóm tắt nhanh

Sandcastle là thư viện TypeScript (giấy phép MIT) để điều phối AI coding agent trong môi trường sandbox cách ly. Bạn gọi một hàm sandcastle.run(), thư viện tự lo sandbox và nhánh git, rồi gộp commit của agent về lại. Dùng được nếu bạn đã quen Node và TypeScript. README của repo chưa ghi lệnh cài, nên bạn cần xem thêm phần docs.

Sandcastle là một thư viện TypeScript để điều phối các AI coding agent trong những sandbox cách ly. Hiểu đơn giản: thay vì để agent sửa thẳng vào thư mục dự án của bạn, bạn giao việc qua một lệnh sandcastle.run(). Agent làm việc trong một "phòng cát" riêng. Xong việc, các commit nó tạo ra được gộp về lại nhánh của bạn.

Repo này dành cho lập trình viên muốn chạy nhiều agent song song, hoặc dựng quy trình kiểm tra code tự động mà không lo agent làm hỏng máy hay làm rối nhánh chính. Tác giả gọi kiểu chạy này là agent "AFK" (đi vắng): bạn giao việc rồi đi làm việc khác. Hiện repo có khoảng 9043 sao và 977 fork, vẫn được cập nhật trong 3 tháng gần đây.

Điểm đáng giá nhất là Sandcastle không buộc bạn vào một nơi chạy cố định. Bạn có thể dùng sandbox của chính hệ điều hành, Docker, Podman, hoặc các dịch vụ đám mây. Nếu chưa quen lập trình thì đây chưa phải công cụ để bấm cài rồi dùng ngay. Nhưng nếu bạn là dev mới, bài này giúp bạn hiểu nó làm gì và bắt đầu từ đâu.

Thư viện

mattpocock/sandcastle

Thư viện TypeScript giúp chạy các AI coding agent trong sandbox cách ly chỉ với một lệnh sandcastle.run(), rồi gộp commit của agent về nhánh của bạn.

★ 9kTypeScriptMIT
Xem repo trên GitHub

I.Sandcastle làm được gì

Theo README, Sandcastle làm ba việc chính, tạo thành một vòng khép kín.

A.Gọi agent bằng một lệnh duy nhất

Bạn chỉ cần gọi sandcastle.run() trong code TypeScript. Bạn không phải tự dựng môi trường, tự tạo nhánh, tự dọn dẹp. Lợi ích thực tế là việc "giao việc cho agent" trở thành một dòng code bạn có thể đặt vào script, vào quy trình tự động, hoặc lặp lại nhiều lần.

B.Cách ly agent bằng sandbox

Agent lập trình thường được cấp quyền chạy lệnh và sửa file. Để nó chạy thẳng trên máy chính thì khá rủi ro. Sandcastle cho agent làm việc trong sandbox, nên nếu nó làm sai thì ảnh hưởng chỉ nằm trong sandbox đó.

C.Chiến lược nhánh có thể cấu hình

Sandcastle xử lý việc sandbox agent "với một chiến lược nhánh (branch strategy) cấu hình được". Mỗi agent làm trên nhánh riêng, và commit của nó được gộp về sau khi xong. Nhờ vậy nhiều agent chạy cùng lúc không đạp lên nhau. README có hẳn một trang tài liệu về các chiến lược nhánh.

D.Không phụ thuộc nhà cung cấp (provider-agnostic)

README liệt kê các kiểu sandbox sau:

  • Sandbox gốc của hệ điều hànhBubblewrap trên Linux và WSL2, Seatbelt trên macOS.
  • Dựa trên imageDocker và Podman.
  • Đám mâyDaytona, E2B, Fly.io Sprites, Modal và Vercel.
  • Tự viếtbạn có thể tạo provider riêng.

Bạn chọn nơi chạy hợp với túi tiền và mức bảo mật, không bị khóa vào một nhà.

E.Những thứ khác có trong tài liệu

Mục lục tài liệu của repo cho thấy còn có agent providers, agent sessions, iterations (vòng lặp), structured output (kết quả có cấu trúc), prompts, hooks, lệnh init, log của mỗi lần chạy, và hàm createSandbox() bên cạnh run(). Phần này mình chỉ nêu tên. Chi tiết cách dùng, bạn xem trong thư mục docs/guide của repo.

II.Cần chuẩn bị gì

README không có mục "yêu cầu hệ thống" riêng. Nó chỉ nhắc rằng trang "Getting started" trong tài liệu có phần prerequisites (điều kiện cần) và quick start. Từ những gì có trong tư liệu, bạn cần:

  • Biết dùng terminal và có Node.js cùng npm. Phần Development của README dùng các lệnh npm, và dự án có package.json. README không nói rõ phiên bản Node tối thiểu. Bạn xem package.json hoặc trang Getting started.
  • Hệ điều hành: Linux, WSL2 (Windows), hoặc macOS đều có sandbox gốc theo README. Docker và Podman là lựa chọn nếu bạn muốn dùng container.
  • Tài khoản dịch vụ đám mây chỉ cần nếu bạn chọn Daytona, E2B, Fly.io Sprites, Modal hay Vercel.
  • Một AI coding agent để Sandcastle điều phối. README có nhắc "agent providers" nhưng không liệt kê trong phần chính. Bạn xem trang Agent providers trong docs để biết agent nào được hỗ trợ và cần key nào.
  • Kho git: vì Sandcastle làm việc với nhánh và commit, dự án của bạn nên là một kho git.

Về phần cứng, tư liệu không đề cập GPU hay cấu hình tối thiểu.

III.Cài đặt từng bước

  1. Mở terminalVào thư mục bạn muốn đặt code
  2. Lấy mã nguồnDùng git clone để tải repo về
  3. Cài phụ thuộcChạy npm install trong thư mục repo
  4. BuildChạy npm run build để đóng gói bằng tsup
  5. Kiểm traChạy npm test và npm run typecheck
  6. Đọc Getting startedXem docs/guide để biết cách dùng trong dự án của bạn

Lưu ý quan trọng: README chưa ghi lệnh cài Sandcastle như một thư viện vào dự án riêng của bạn. Phần "Development" trong README là các bước dành cho người muốn sửa chính repo. Tư liệu cho biết gói npm tên là @ai-hero/sandcastle và có lệnh CLI. Cách cài và dùng trong dự án của bạn, hãy xem trang Getting started trong docs/guide, hoặc tại aihero.dev/sandcastle.

Dưới đây là các bước tải và chạy repo về máy, đúng như README.

A.Mở terminal đúng chỗ

Trên Windows, bạn mở PowerShell hoặc Terminal. Trên macOS hay Linux, mở ứng dụng Terminal. Dùng lệnh cd để vào thư mục bạn muốn lưu code. Người mới hay quên bước này nên lệnh sau chạy nhầm chỗ.

B.Tải mã nguồn về máy

Lệnh git clone sao chép toàn bộ repo về máy. Lệnh cd đi vào thư mục vừa tạo.

Terminal
git clone https://github.com/mattpocock/sandcastle.git
cd sandcastle

Nếu máy báo không có git, bạn cần cài Git trước.

C.Cài các gói phụ thuộc

Lệnh này đọc package.json và tải mọi gói repo cần. Phải chạy trong thư mục sandcastle vừa vào. Lần đầu có thể mất vài phút.

Terminal
npm install

D.Build và chạy thử

README ghi ba lệnh cho phần phát triển. Mỗi lệnh có chú thích ngay trong README:

Terminal
npm run build    # Bundle with tsup
npm test         # Run tests with vitest
npm run typecheck # Type-check

npm run build đóng gói thư viện bằng tsup. npm test chạy bộ kiểm thử bằng vitest. npm run typecheck kiểm tra kiểu dữ liệu TypeScript.

Chạy agent có quyền sửa code và chạy lệnh thì có thể tốn tiền (nếu dùng dịch vụ đám mây hoặc API có tính phí) và có rủi ro an toàn. Hãy thử trên kho git thử nghiệm trước, đừng cho agent chạm vào dự án quan trọng khi bạn chưa hiểu cách cấu hình sandbox và nhánh. Không dán key bí mật vào file mà bạn sẽ đẩy lên GitHub.

IV.Kiểm tra đã chạy được chưa

README không mô tả màn hình hay kết quả mong đợi cho phần dùng thư viện. Với phần Development, cách kiểm tra hợp lý nhất là dùng chính các lệnh trong README:

  • npm run build chạy xong, không báo lỗi đỏ.
  • npm test chạy hết bộ test mà không có test nào thất bại.
  • npm run typecheck kết thúc mà không báo lỗi kiểu.

Kết quả cụ thể (số test, thời gian) tư liệu không nêu, nên mình không đoán. Một số test có thể cần Docker hay công cụ sandbox trên máy. Repo có cả vitest.config.ts và vitest.local.config.ts, nên nếu có test lỗi thì bạn xem hai file này cùng package.json để biết test nào chạy ở đâu.

Với việc dùng thật, dấu hiệu thành công là sau khi gọi sandcastle.run(), bạn thấy một nhánh với các commit do agent tạo được gộp về. Trang "Run logs" trong docs nói về nhật ký mỗi lần chạy, nên bạn có thể xem ở đó.

V.Dùng vào việc thật

README chỉ nêu mục đích ở mức khái quát: chạy song song nhiều agent AFK, dựng quy trình review, hoặc điều phối agent của riêng bạn. Các tình huống dưới đây bám theo ba hướng đó. Tên tùy chọn cụ thể của run() mình không ghi vì README không liệt kê. Bạn xem trang tham chiếu run() và createSandbox().

Giao việc cho agent rồi đi làm việc khác, nhưng đừng để nó làm trên nhánh chính của bạn.

Ông T

A.Dev đơn lẻ giao nhiều việc nhỏ cùng lúc

Bối cảnh: bạn là dev freelance, cuối tuần có ba việc lặt vặt: sửa một lỗi hiển thị, thêm test cho một hàm, đổi tên một biến khắp dự án. Làm tay thì mất cả buổi.

Cách làm: viết một script TypeScript gọi sandcastle.run() ba lần, mỗi lần một mô tả việc riêng. Chọn chiến lược nhánh để mỗi agent làm trên nhánh của mình. Chạy script, rồi đi pha cà phê.

Kết quả: mỗi agent tạo commit trên nhánh riêng và được gộp về theo chiến lược bạn chọn. Bạn chỉ cần đọc lại các commit và quyết định giữ cái nào.

B.Dựng bước review code tự động

Bối cảnh: nhóm của bạn có vài lập trình viên, và bạn muốn mỗi thay đổi lớn được một agent đọc qua trước khi người thật xem.

Cách làm: README nói Sandcastle phù hợp để "tạo review pipeline". Bạn chạy một agent viết code, rồi một agent khác (trong sandbox khác) đọc thay đổi và nhận xét. Trang Prompts và Structured output trong docs hướng dẫn cách đưa yêu cầu và nhận kết quả có cấu trúc.

Kết quả: người review thật nhận một bản thay đổi đã có sẵn nhận xét sơ bộ, đỡ mất thời gian cho lỗi nhỏ.

C.Thử agent trên mã lạ mà không lo cho máy chính

Bối cảnh: bạn muốn cho agent chạy thử một repo bạn mới tải về, nhưng ngại nó chạy lệnh lung tung trên máy làm việc.

Cách làm: chọn sandbox cách ly, ví dụ Docker hoặc Podman, hoặc sandbox gốc của hệ điều hành (Bubblewrap, Seatbelt). Gọi sandcastle.run() để agent làm việc bên trong.

Kết quả: việc agent làm diễn ra trong sandbox. Bạn chỉ nhận lại commit trên nhánh. Cách này an toàn hơn chạy thẳng, nhưng mức bảo vệ còn phụ thuộc loại sandbox bạn chọn.

D.Tự viết provider sandbox cho hệ thống của công ty

Bối cảnh: công ty bạn có hạ tầng riêng, không dùng các dịch vụ có sẵn.

Cách làm: README nói bạn có thể tạo provider của riêng mình. Bạn xem trang Sandbox providers và phần Glossary để biết thuật ngữ.

Kết quả: Sandcastle chạy agent trên hạ tầng của chính bạn, trong khi cách gọi sandcastle.run() vẫn giữ nguyên.

VI.Lỗi hay gặp và cách xử lý

Tư liệu không có mục xử lý sự cố. Các lỗi dưới đây là những chỗ người mới rất dễ vấp với loại công cụ này.

A.npm install báo lỗi hoặc không thấy lệnh npm

Thường là do chưa cài Node.js, hoặc đang mở terminal ở sai thư mục. Cài Node.js trước. Sau đó chắc chắn bạn đã cd sandcastle rồi mới chạy lại. Nếu báo phiên bản Node không phù hợp, xem package.json để biết yêu cầu.

B.Sandbox không khởi động được

Nếu bạn chọn Docker hay Podman mà chưa bật ứng dụng, agent sẽ không có chỗ để chạy. Hãy mở Docker hoặc Podman và kiểm tra nó đang chạy. Với Bubblewrap hay Seatbelt, kiểm tra bạn đang dùng đúng hệ điều hành (Linux/WSL2 cho Bubblewrap, macOS cho Seatbelt). Chi tiết trong trang Sandbox providers.

C.Agent chạy xong nhưng không thấy commit

Nguyên nhân hay gặp là cấu hình chiến lược nhánh chưa đúng ý, hoặc dự án chưa phải kho git. Kiểm tra bằng git branch và git log xem commit nằm ở nhánh nào. Sau đó đối chiếu trang Branch strategies.

D.Thiếu key hoặc tài khoản cho agent hay dịch vụ đám mây

Agent và các dịch vụ như E2B, Modal hay Vercel thường cần tài khoản hoặc khóa truy cập. Tư liệu không nêu tên biến môi trường nào, nên mình không đoán. Hãy xem trang Agent providers và Sandbox providers. Tuyệt đối không dán key vào code rồi đẩy lên GitHub.

E.Test thất bại khi chạy npm test

Một số test có thể cần công cụ sandbox có sẵn trên máy. Đọc kỹ thông báo lỗi để xem test nào hỏng. Xem package.json, vitest.config.ts và vitest.local.config.ts. Nếu vẫn kẹt, tìm trong phần Issues của repo.

VII.Có nên dùng không

Điểm mạnh:

  • Một lệnh sandcastle.run() gói gọn việc sandbox, nhánh và gộp commit.
  • Nhiều lựa chọn nơi chạy: sandbox hệ điều hành, container, đám mây, hoặc tự viết.
  • Phù hợp chạy song song nhiều agent và dựng quy trình review.
  • Giấy phép MIT, repo đông người quan tâm (khoảng 9043 sao) và còn cập nhật.
  • Có tài liệu riêng chia theo chủ đề, kèm bảng thuật ngữ.

Giới hạn:

  • Đây là thư viện cho người viết code TypeScript, không phải ứng dụng bấm là chạy. Người làm văn phòng chưa biết lập trình sẽ thấy khó.
  • README ngắn, không có hướng dẫn cài và dùng từng bước. Bạn phải đọc thêm docs/guide.
  • Mức an toàn phụ thuộc loại sandbox bạn chọn và cách bạn cấu hình. Tư liệu không cam kết bảo mật tuyệt đối.
  • Tư liệu không nói về chi phí khi dùng agent hay dịch vụ đám mây.

Khi nào chọn cách khác: nếu bạn chỉ cần một trợ lý lập trình chạy tay ngay trong editor hoặc terminal, không cần tự động hóa, thì dùng thẳng công cụ agent đó sẽ đơn giản hơn. Sandcastle đáng thử khi bạn muốn giao việc hàng loạt, chạy song song, hoặc cần cách ly agent khỏi máy chính.

4.9/5 · Ông T chấm

Chưa có độc giả chấm

Bài này có ích với bạn không?

Câu hỏi thường gặp

Sandcastle có miễn phí không?

Bản thân thư viện dùng giấy phép MIT nên bạn dùng và sửa tự do. Tuy vậy, tư liệu không nói gì về chi phí của agent hay các dịch vụ đám mây như Daytona, E2B, Modal, Vercel. Phần đó bạn cần xem điều khoản của từng nhà cung cấp.

Sandcastle có chạy được trên Windows không?

README nói sandbox gốc dùng Bubblewrap trên Linux và WSL2, Seatbelt trên macOS. Như vậy trên Windows bạn có thể dùng qua WSL2. Ngoài ra còn có Docker, Podman và các nhà cung cấp đám mây. Tư liệu không nói rõ về chạy trực tiếp trên Windows không qua WSL2.

Cần GPU hay máy cấu hình mạnh không?

Tư liệu không đề cập yêu cầu GPU hay cấu hình tối thiểu. Sandcastle chỉ điều phối agent trong sandbox. Mức tài nguyên cần thêm phụ thuộc vào agent và sandbox bạn chọn.

Sandcastle dùng những sandbox nào?

Theo README: sandbox gốc của hệ điều hành (Bubblewrap, Seatbelt), image-based cho Docker và Podman, và cloud cho Daytona, E2B, Fly.io Sprites, Modal, Vercel. Bạn cũng có thể tự tạo provider riêng.

Dữ liệu và mã nguồn của tôi có an toàn không?

Mục đích của sandbox là cách ly agent khỏi máy chính của bạn. Tuy nhiên tư liệu không nêu cam kết bảo mật cụ thể. Nếu bạn chọn dịch vụ đám mây thì code sẽ chạy ở đó, nên hãy đọc chính sách của nhà cung cấp. Với mã nhạy cảm, nên thử trên sandbox cục bộ và kho git thử nghiệm trước.

Người không biết lập trình có dùng được không?

Sandcastle là thư viện TypeScript, bạn gọi nó bằng code. Vì vậy người chưa biết lập trình sẽ khó dùng một mình. Dev mới thì có thể bắt đầu bằng trang Getting started trong docs.

Cài Sandcastle vào dự án của tôi bằng lệnh nào?

README chưa ghi lệnh này. Tư liệu chỉ cho biết gói npm tên là @ai-hero/sandcastle và có lệnh CLI. Bạn xem trang Getting started và Init trong thư mục docs/guide của repo, hoặc tại aihero.dev/sandcastle.

Chuyển nhanh tới mục

  1. I.Sandcastle làm được gì
    1. A.Gọi agent bằng một lệnh duy nhất
    2. B.Cách ly agent bằng sandbox
    3. C.Chiến lược nhánh có thể cấu hình
    4. D.Không phụ thuộc nhà cung cấp (provider-agnostic)
    5. E.Những thứ khác có trong tài liệu
  2. II.Cần chuẩn bị gì
  3. III.Cài đặt từng bước
    1. A.Mở terminal đúng chỗ
    2. B.Tải mã nguồn về máy
    3. C.Cài các gói phụ thuộc
    4. D.Build và chạy thử
  4. IV.Kiểm tra đã chạy được chưa
  5. V.Dùng vào việc thật
    1. A.Dev đơn lẻ giao nhiều việc nhỏ cùng lúc
    2. B.Dựng bước review code tự động
    3. C.Thử agent trên mã lạ mà không lo cho máy chính
    4. D.Tự viết provider sandbox cho hệ thống của công ty
  6. VI.Lỗi hay gặp và cách xử lý
    1. A.npm install báo lỗi hoặc không thấy lệnh npm
    2. B.Sandbox không khởi động được
    3. C.Agent chạy xong nhưng không thấy commit
    4. D.Thiếu key hoặc tài khoản cho agent hay dịch vụ đám mây
    5. E.Test thất bại khi chạy npm test
  7. VII.Có nên dùng không

Repo & Skill · 13/11/2026 · 11 phút đọc

Garden Skills: bộ skill thiết kế web, tạo ảnh, làm video cho AI — hướng dẫn cài đặt và dùng

Garden Skills là bộ sưu tập Agent Skills (kỹ năng cho AI) của tác giả ConardLi, dùng được với Claude Code, Cursor, Codex và các AI coding agent khác. Mỗi skill dạy agent làm tốt một việc như thiết kế trang web, tạo ảnh, làm video bằng code, biến tài liệu thành bài viết đẹp. Cài không khó, nhưng README có nhiều cách cài nên bạn cần chọn một cách hợp với công cụ đang dùng.

Repo & Skill · 13/11/2026 · 15 phút đọc

thesysdev/openui: xây giao diện AI dạng streaming — hướng dẫn cài đặt và dùng

OpenUI là framework full-stack, độc lập framework, giúp mô hình AI sinh giao diện có cấu trúc và hiển thị dần khi dữ liệu streaming về. Bạn có thể dựng nhanh một ứng dụng chat bằng CLI hoặc cài từng gói cho React, Vue, Svelte, Angular và LangChain. Việc bắt đầu khá đơn giản nếu máy có đúng phiên bản Node; README chưa ghi đầy đủ lệnh chạy ứng dụng sau khi scaffold.

Repo & Skill · 13/11/2026 · 11 phút đọc

Ruflo: điều phối nhóm agent AI cho Claude Code và Codex — hướng dẫn cài đặt và dùng

Ruflo (trước đây là Claude Flow) là một agent harness: lớp công cụ bao quanh Claude Code và Codex, bổ sung nhiều agent chuyên biệt, bộ nhớ qua các phiên và khả năng chia việc cho nhóm agent. Cài bằng một lệnh `npx ruflo@latest init` trong thư mục dự án, cần Node 20 trở lên. Cài khá dễ, nhưng hệ thống rất rộng nên bạn nên bắt đầu từ một tác vụ nhỏ.