Sandcastle: chạy AI coding agent trong sandbox bằng TypeScript — hướng dẫn cài đặt và dùng
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 →

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.
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.
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 xempackage.jsonhoặ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
- Mở terminalVào thư mục bạn muốn đặt code
- Lấy mã nguồnDùng git clone để tải repo về
- Cài phụ thuộcChạy npm install trong thư mục repo
- BuildChạy npm run build để đóng gói bằng tsup
- Kiểm traChạy npm test và npm run typecheck
- Đọ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.
git clone https://github.com/mattpocock/sandcastle.git
cd sandcastleNế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.
npm installD.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:
npm run build # Bundle with tsup
npm test # Run tests with vitest
npm run typecheck # Type-checknpm 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 buildchạy xong, không báo lỗi đỏ.npm testchạy hết bộ test mà không có test nào thất bại.npm run typecheckkế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.
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.


