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 để điều phối AI coding agent trong môi trường sandbox cô lập. Bạn gọi một hàm sandcastle.run(), agent làm việc trên nhánh riêng, rồi các commit được gộp về lại. Với người đã quen npm thì cài không khó, nhưng người mới nên đọc kỹ tài liệu trong docs/guide của repo.

Sandcastle là một thư viện TypeScript giúp bạn chạy các AI coding agent bên trong môi trường sandbox cô lập. Bạn chỉ cần gọi một hàm sandcastle.run(). Thư viện lo phần cách ly agent, tạo nhánh riêng cho agent làm việc, rồi gộp các commit của agent về lại.

Vấn đề nó giải quyết khá đời thường: giao cho agent viết code thì tiện, nhưng thả nó chạy thẳng trên máy mình thì ngại. Agent có thể sửa lung tung, chạy lệnh lạ, hoặc làm rối nhánh đang làm dở. Sandcastle đặt agent vào một "hộp cát" riêng, để nó làm việc ở đó và chỉ mang kết quả (các commit) trở về.

Repo này hợp với lập trình viên, kể cả người mới, đã dùng qua AI coding agent và muốn chạy nhiều agent song song hoặc dựng quy trình tự động. Điểm đáng giá nhất là tính trung lập về nhà cung cấp sandbox: bạn có thể chọn sandbox ngay trên máy (Bubblewrap, Seatbelt), Docker, Podman hoặc dịch vụ đám mây, tuỳ nhu cầu. Hiện repo có khoảng 9.033 sao và 976 fork, giấy phép MIT, và vẫn được cập nhật trong vài tháng gần đây.

Thư viện

mattpocock/sandcastle

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

★ 9kTypeScriptMIT
Xem repo trên GitHub

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

Hiểu đơn giản, Sandcastle là lớp điều phối đứng giữa code của bạn và các AI agent. Các tính năng chính theo tư liệu:

  • Một lệnh gọi là chạy agent. Bạn gọi sandcastle.run() từ code TypeScript. Bạn không phải tự dựng môi trường, tự tạo nhánh, tự gộp kết quả. Lợi ích là bạn tập trung vào việc muốn agent làm, không mất thời gian lo hạ tầng.
  • Cô lập agent trong sandbox. Agent chạy trong môi trường riêng, nên lỡ làm sai cũng ít ảnh hưởng đến máy và thư mục làm việc chính của bạn.
  • Chiến lược nhánh (branch strategy) cấu hình được. Agent làm việc trên nhánh riêng, và các commit trên nhánh đó được gộp lại. Bạn vẫn có lịch sử git rõ ràng để xem agent đã làm gì.
  • Không phụ thuộc một nhà cung cấp sandbox nào. README liệt kê:
    • sandbox gốc dùng cơ chế cách ly của hệ điều hành: Bubblewrap trên Linux và WSL2, Seatbelt trên macOS;
    • sandbox dựa trên image: Docker và Podman;
    • sandbox đám mây: Daytona, E2B, Fly.io Sprites, Modal và Vercel;
    • hoặc tự viết nhà cung cấp riêng của bạn.
  • Phù hợp cho nhiều kiểu dùng. README nhấn mạnh ba hướng: chạy song song nhiều agent "AFK" (agent tự làm khi bạn vắng mặt), dựng pipeline review code, hoặc đơn giản là điều phối agent của riêng bạn.
  • Tài liệu theo từng khái niệm. Thư mục docs/guide chia mỗi trang một thuật ngữ lớn: sandbox, nhánh, agent, phiên agent, vòng lặp (iterations), kết quả có cấu trúc (structured output), prompt, hook, init, nhật ký chạy (run logs), cùng một bảng thuật ngữ (Glossary). Tài liệu cũng được đăng tại aihero.dev/sandcastle.

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

Tư liệu README ngắn nên phần này mình chỉ nêu những gì có thật:

  • Node.js và npm. Repo là dự án TypeScript, có package.json, và README dùng npm install. README ở đây không ghi phiên bản Node tối thiểu. Phần "prerequisites" (điều kiện cần) nằm trong trang Getting started của docs/guide, bạn nên xem ở đó.
  • Một loại sandbox để chạy agent. Tuỳ lựa chọn của bạn:
    • Linux hoặc WSL2: Bubblewrap.
    • macOS: Seatbelt.
    • Docker hoặc Podman nếu muốn dùng image.
    • Tài khoản dịch vụ đám mây nếu chọn Daytona, E2B, Fly.io Sprites, Modal hoặc Vercel.
  • Một AI coding agent. Sandcastle điều phối agent chứ không tự là agent. Các loại agent được hỗ trợ nằm ở trang Agent providers trong tài liệu. README chưa liệt kê tên cụ thể, nên bạn cần xem trang đó.
  • API key / tài khoản của agent hoặc dịch vụ đám mây (nếu dùng). README chưa nói rõ cần key nào. Hãy xem tài liệu của từng provider.

Agent chạy trong sandbox vẫn có thể tốn chi phí (API của agent, dịch vụ đám mây). Đừng dán key vào code rồi đẩy lên GitHub. Với agent chạy tự động nhiều vòng, nên theo dõi mức chi tiêu ngay từ lần chạy đầu.

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

README của repo chỉ ghi cách cài để phát triển (tải mã nguồn về, build, chạy test). Cách dùng gói như một thư viện trong dự án của bạn nằm ở trang Getting started trong docs/guide. Mình chia thành hai hướng để bạn chọn.

  1. Mở terminalMở đúng thư mục dự án (hoặc thư mục sẽ chứa mã nguồn)
  2. Lấy mã nguồnDùng git clone để tải repo về máy
  3. Cài phụ thuộcChạy npm install
  4. BuildChạy npm run build để đóng gói bằng tsup
  5. Kiểm traChạy npm test và npm run typecheck

A.Mở terminal đúng chỗ

Trên Windows, bạn có thể dùng PowerShell hoặc Git Bash. Trên macOS/Linux, dùng Terminal. Nếu định dùng sandbox Bubblewrap trên Windows, README nói nó hỗ trợ qua WSL2, nên hãy mở terminal WSL2. Người mới hay vấp ở chỗ chạy lệnh sai thư mục, nên kiểm tra bằng lệnh cd trước khi chạy tiếp.

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

Lệnh này tải toàn bộ repo về một thư mục tên sandcastle, rồi bạn đi vào thư mục đó. Cần có Git trên máy.

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

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. Bạn cần Node.js và npm đã cài sẵn. Lần đầu có thể mất vài phút.

Terminal
npm install

D.Build thư viện

README ghi bước này dùng tsup để đóng gói mã nguồn TypeScript.

Terminal
npm run build

E.Chạy test và kiểm tra kiểu

Hai lệnh này đều có trong README. Chúng giúp bạn chắc chắn bản tải về hoạt động bình thường trên máy mình.

Terminal
npm test
npm run typecheck

F.Nếu bạn chỉ muốn dùng trong dự án của mình

Tên gói trên npm là @ai-hero/sandcastle, và gói có kèm lệnh CLI. README không ghi lệnh cài kiểu này, nhưng với một gói npm thông thường thì cách cài là:

Terminal
npm install @ai-hero/sandcastle

Sau đó, README chưa ghi cách khởi tạo và cấu hình cụ thể. Hãy đọc trang Getting started, Init và CLI commands trong docs/guide của repo để làm đúng các bước tiếp theo, vì đó là nơi tác giả hướng dẫn chính thức.

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

Theo README, cách kiểm tra rõ ràng nhất là các lệnh của phần phát triển:

  • npm run build chạy xong không báo lỗi, nghĩa là đóng gói thành công.
  • npm test chạy bộ test bằng vitest. Kết quả mong đợi là các test đều qua.
  • npm run typecheck chạy kiểm tra kiểu của TypeScript. Không có lỗi in ra nghĩa là ổn.

Với trường hợp bạn cài gói vào dự án riêng, README chưa nêu màn hình hay kết quả mong đợi cụ thể. Cách an toàn là làm theo ví dụ trong trang Getting started (phần quick start) rồi xem nhật ký chạy, vì tài liệu có hẳn một trang về run logs. Dấu hiệu thành công đúng nghĩa là agent chạy xong và các commit của nó xuất hiện trên nhánh theo chiến lược nhánh bạn chọn.

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

Phần này là những tình huống bám vào khả năng README nêu: chạy song song, pipeline review và điều phối agent riêng. Mình không đưa lệnh chi tiết ngoài README, vì cú pháp tuỳ chọn của sandcastle.run() nằm trong trang tham chiếu run() và createSandbox().

A.Dev nhỏ cho agent làm việc lặt vặt trong lúc đi ăn trưa

Bối cảnh: bạn là lập trình viên tự do, có một danh sách việc nhỏ như đổi tên biến, viết thêm test, dọn code. Bạn viết một script TypeScript gọi sandcastle.run() với việc cần làm, rồi để agent chạy trong sandbox. Đây đúng là kiểu "AFK agent" mà README nhắc tới. Khi quay lại, bạn xem các commit trên nhánh của agent và quyết định giữ hay bỏ. Việc chạy trong sandbox giúp bạn yên tâm hơn so với để agent làm trực tiếp trên thư mục đang làm dở.

Giao việc cho agent không đáng sợ nếu nó làm trong hộp cát và chỉ trả về commit để bạn duyệt.

Ông T

B.Nhóm nhỏ chạy nhiều agent song song

Bối cảnh: một nhóm hai ba người có nhiều ticket độc lập. Mỗi ticket giao cho một lần sandcastle.run(), mỗi lần làm trên nhánh riêng của nó. Vì mỗi agent có sandbox và nhánh riêng nên không giẫm chân nhau. Kết quả là bạn nhận về nhiều nhánh, mỗi nhánh một việc, và duyệt từng cái như duyệt pull request bình thường.

C.Dựng pipeline review code

Bối cảnh: bạn muốn mỗi thay đổi đều được "đọc thử" bởi một agent trước khi người thật xem. README liệt kê "review pipelines" là một mục đích dùng. Bạn có thể cho một agent viết code, sau đó một agent khác chạy trong sandbox khác để review. Tài liệu có trang về kết quả có cấu trúc (structured output) và vòng lặp (iterations), hai thứ rất hợp để bắt agent trả về kết quả đọc được bằng chương trình thay vì văn bản tự do. Hãy xem hai trang này khi dựng pipeline.

D.Tự viết nhà cung cấp sandbox hoặc agent riêng

Bối cảnh: công ty bạn có hạ tầng riêng hoặc quy định bảo mật riêng. README nói bạn có thể tự tạo nhà cung cấp sandbox, và phần "orchestrating your own agents" cho thấy repo cũng phục vụ trường hợp dùng agent tự chọn. Cách làm cụ thể nằm ở trang Sandbox providers và Agent providers trong tài liệu. Kết quả là bạn giữ được quy trình chung của Sandcastle (nhánh, gộp commit) mà vẫn chạy trên môi trường của mình.

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

Tư liệu không liệt kê lỗi cụ thể, nên các mục dưới đây là những vướng mắc rất dễ xảy ra với loại công cụ này. Mình chỉ gợi hướng kiểm tra, không đưa thông báo lỗi chính xác.

  • npm install hoặc npm run build lỗi. Thường do phiên bản Node quá cũ hoặc chạy lệnh sai thư mục. Hãy kiểm tra bạn đang ở trong thư mục sandcastle (có file package.json). Xem trang prerequisites trong tài liệu để biết phiên bản Node cần dùng.
  • Sandbox không khởi động được. Có thể bạn chưa cài thành phần mà provider cần. Ví dụ Docker hoặc Podman chưa chạy, hoặc Bubblewrap chưa có trong WSL2. Hãy bật hoặc cài thành phần đó, rồi thử lại với một lần chạy đơn giản trước.
  • Agent không đăng nhập được hoặc báo thiếu key. Agent và dịch vụ đám mây thường cần thông tin xác thực. Hãy làm đúng theo trang Agent providers, và đừng dán key vào file rồi commit lên git.
  • Commit của agent không thấy ở nhánh bạn đang xem. Agent làm trên nhánh riêng theo chiến lược nhánh bạn chọn. Hãy đọc trang Branch strategies để biết commit được gộp về đâu, rồi dùng git branch và git log để kiểm tra.
  • Chi phí tăng bất ngờ. Chạy nhiều agent song song hoặc nhiều vòng lặp có thể tốn tiền gọi API và dịch vụ đám mây. Hãy bắt đầu với một việc nhỏ, xem nhật ký chạy, rồi mới tăng quy mô.

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

Điểm mạnh:

  • Một hàm sandcastle.run() gói gọn việc cách ly, tạo nhánh và gộp commit.
  • Nhiều lựa chọn sandbox: ngay trên máy, Docker/Podman, hoặc đám mây, kèm khả năng tự viết provider.
  • Tài liệu được tổ chức rõ theo từng khái niệm và có bảng thuật ngữ.
  • Giấy phép MIT, cộng đồng khá lớn (khoảng 9.033 sao) và vẫn được cập nhật gần đây.

Giới hạn:

  • Đây là thư viện cho lập trình viên, không phải ứng dụng bấm là chạy. Bạn cần viết một ít TypeScript.
  • README khá ngắn, hầu hết hướng dẫn thật nằm trong docs/guide. Người hoàn toàn mới sẽ phải đọc thêm.
  • Chưa có thông tin trong tư liệu về yêu cầu phần cứng, phiên bản Node tối thiểu hay mức chi phí.

Khi nào nên chọn cách khác: nếu bạn chỉ cần hỏi đáp hoặc nhờ AI sửa vài dòng code, dùng thẳng công cụ coding agent là đủ, không cần dựng thêm lớp điều phối. Sandcastle đáng thử khi bạn muốn chạy agent tự động, nhiều agent cùng lúc, hoặc cần cách ly chặt hơn.

4.5/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, tức là mã nguồn mở. Tuy nhiên README không nói 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 theo từng nhà cung cấp.

Sandcastle 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. Docker, Podman và các dịch vụ đám mây cũng được hỗ trợ. Tư liệu không nói rõ về chạy trực tiếp trên Windows ngoài WSL2, nên bạn hãy xem trang prerequisites trong docs/guide.

Cần GPU hoặc cấu hình mạnh không?

Tư liệu chưa có thông tin về yêu cầu phần cứng. Sandcastle điều phối agent trong sandbox chứ không tự chạy mô hình AI, nhưng bạn nên xem tài liệu để biết rõ.

Agent chạy trong Sandcastle có an toàn cho code của tôi không?

Agent được cô lập trong sandbox và làm việc trên nhánh riêng, sau đó commit mới được gộp về lại. Cách này giảm rủi ro so với để agent chạy thẳng trên thư mục chính. Mức bảo vệ cụ thể phụ thuộc loại sandbox bạn chọn, và tư liệu không cam kết điều gì hơn thế.

Sandcastle khác gì việc dùng thẳng một AI coding agent?

Sandcastle không thay thế agent mà điều phối agent từ code TypeScript. Nó lo sandbox, nhánh và gộp commit để bạn chạy nhiều agent, tự động hoá hoặc dựng pipeline review. Nếu chỉ cần nhờ AI sửa code thủ công thì dùng thẳng agent là đủ.

Cài Sandcastle như thế nào?

README ghi cách cài để phát triển: git clone repo, rồi chạy npm install, npm run build, npm test. Gói npm tên @ai-hero/sandcastle và có lệnh CLI. Hướng dẫn dùng trong dự án riêng nằm ở trang Getting started trong docs/guide.

Tôi có thể dùng nhà cung cấp sandbox của riêng mình không?

Có. README nói Sandcastle không phụ thuộc nhà cung cấp và bạn có thể tạo provider riêng. Cách làm chi tiết nằm ở trang Sandbox providers trong tài liệu.

Chuyển nhanh tới mục

  1. I.Sandcastle làm được gì
  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 thư viện
    5. E.Chạy test và kiểm tra kiểu
    6. F.Nếu bạn chỉ muốn dùng trong dự án của mình
  4. IV.Kiểm tra đã chạy được chưa
  5. V.Dùng vào việc thật
    1. A.Dev nhỏ cho agent làm việc lặt vặt trong lúc đi ăn trưa
    2. B.Nhóm nhỏ chạy nhiều agent song song
    3. C.Dựng pipeline review code
    4. D.Tự viết nhà cung cấp sandbox hoặc agent riêng
  6. VI.Lỗi hay gặp và cách xử lý
  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ỏ.