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

> Sandcastle là thư viện TypeScript (giấy phép MIT) giúp bạn điều phối các AI coding agent chạy trong môi trường cô lập, chỉ với một lệnh sandcastle.run(). Agent làm việc trên nhánh riêng, xong thì commit được gộp ngược về. Cài qua npm khá đơn giản, nhưng bạn cần biết TypeScript/Node ở mức cơ bản và đọc thêm tài liệu trong repo để cấu hình.

- Tác giả: Ông T (https://ongt.vn/gioi-thieu)
- Chủ đề: Repo & Skill
- Đăng: 2026-05-22 · Cập nhật: 2026-11-14
- URL: https://ongt.vn/bai-viet/sandcastle-chay-ai-coding-agent-trong-sandbox-typescript-2

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

Vấn đề repo giải quyết khá quen thuộc. Khi để AI tự sửa code, bạn thường lo nó chạy lệnh lung tung trên máy mình, hoặc nhiều agent chạy cùng lúc đạp lên file của nhau. Sandcastle tách mỗi agent vào một sandbox riêng và quản lý nhánh Git cho từng agent. Nhờ vậy bạn yên tâm để agent làm việc "không cần ngồi canh" (tác giả gọi là AFK agent), kể cả khi chạy song song nhiều agent.

Repo hợp với lập trình viên, người làm tự động hoá, và đội muốn dựng quy trình kiểu "agent viết code, agent khác review". Điểm đáng giá nhất là tính linh hoạt về sandbox: từ sandbox ngay trên hệ điều hành đến Docker, Podman hay dịch vụ đám mây. Hiện repo có khoảng 9.043 sao và 977 fork, vẫn được cập nhật trong 3 tháng gần đây.

```repo
- repo | mattpocock/sandcastle
- kind | Thư viện
- desc | Thư viện TypeScript cho phép gọi sandcastle.run() để chạy AI coding agent trong sandbox cô lập, rồi tự gộp commit của agent về nhánh của bạn.
- stars | 9k
- lang | TypeScript
- license | MIT
```

## Sandcastle làm được gì

### Gọi agent bằng một hàm duy nhất

Bạn không phải tự viết logic tạo môi trường, chép code vào, chạy agent, rồi lấy kết quả ra. Tất cả gói trong `sandcastle.run()`. Với người mới, điều này nghĩa là bạn tập trung vào việc "muốn agent làm gì" thay vì "dựng môi trường thế nào".

### Mỗi agent một nhánh riêng, commit tự gộp về

Sandcastle xử lý việc cô lập agent theo một chiến lược nhánh (branch strategy) có thể cấu hình. Các commit agent tạo ra trên nhánh được gộp ngược lại. Bạn xem lịch sử Git như bình thường, thấy rõ agent đã đổi gì, và có thể hoàn tác nếu không ưng.

### Nhiều loại sandbox để chọn

Theo README, Sandcastle không gắn chặt với một nhà cung cấp nào (provider-agnostic). Các lựa chọn gồm:

- Sandbox gốc của hệ điều hành: Bubblewrap trên Linux và WSL2, Seatbelt trên macOS.
- Sandbox dạng image: Docker và Podman.
- Sandbox đám mây: Daytona, E2B, Fly.io Sprites, Modal và Vercel.
- Tự viết provider riêng nếu cần.

Nhờ vậy bạn có thể bắt đầu nhẹ trên máy cá nhân, sau này chuyển sang đám mây mà không phải đổi cách làm.

### Chạy song song và dựng pipeline review

README nói thư viện rất hợp để chạy song song nhiều agent AFK, tạo pipeline review, hoặc đơn giản là điều phối agent của riêng bạn. Ví dụ: một agent viết code, một agent khác đọc lại và nhận xét.

### Tài liệu chia theo chủ đề

Thư mục `docs/guide` có mỗi trang cho một khái niệm lớn: sandbox, chiến lược nhánh, agent provider, phiên agent (agent sessions), vòng lặp (iterations), đầu ra có cấu trúc (structured output), prompt, hook, init, log chạy, cùng phần tham chiếu cho `run()`, `createSandbox()` và các lệnh CLI. Mọi thuật ngữ đều có định nghĩa trong Glossary. Bản web nằm ở aihero.dev/sandcastle.

## Cần chuẩn bị gì

Tư liệu README không liệt kê chi tiết yêu cầu hệ thống trong phần mình có. Phần "prerequisites" nằm trong tài liệu Getting started của repo. Từ những gì README nói, bạn nên có:

- Môi trường Node.js và npm, vì repo là gói TypeScript phát hành trên npm với tên `@ai-hero/sandcastle`. Gói có lệnh CLI đi kèm.
- Một hệ điều hành phù hợp với loại sandbox bạn chọn: Linux hoặc WSL2 (Bubblewrap), macOS (Seatbelt), hoặc máy có Docker/Podman nếu dùng sandbox dạng image.
- Tài khoản ở nhà cung cấp đám mây (Daytona, E2B, Fly.io, Modal, Vercel) nếu bạn chọn sandbox đám mây.
- Một AI coding agent để Sandcastle điều phối. README nhắc có "agent providers" nhưng không nêu cụ thể trong phần này, nên bạn xem trang Agent providers trong `docs/guide`.

Phiên bản Node tối thiểu, API key và yêu cầu phần cứng: README chưa ghi. Bạn xem `package.json` và trang prerequisites trong tài liệu để có con số chính xác.

```note
Agent AI thường cần API key hoặc đăng nhập tài khoản. Đừng dán key vào file code rồi đẩy lên GitHub. Hãy xem tài liệu của repo để biết cách truyền key vào sandbox an toàn. Nếu dùng sandbox đám mây, hãy theo dõi chi phí vì dịch vụ đám mây có thể tính tiền theo thời gian chạy.
```

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

```steps
- Chuẩn bị Node và npm | Kiểm tra máy đã có Node.js và npm
- Cài gói vào dự án | Thêm @ai-hero/sandcastle vào dự án TypeScript của bạn
- Đọc phần Getting started | Xem prerequisites và quick start trong docs/guide
- Chọn sandbox | Chọn provider phù hợp: native, Docker/Podman hoặc đám mây
- (Tuỳ chọn) Cài từ mã nguồn | Clone repo để build và chạy test nếu muốn đóng góp
```

### Kiểm tra máy đã có Node và npm

Mở terminal (PowerShell trên Windows, Terminal trên macOS/Linux) rồi gõ hai lệnh dưới đây. Nếu hiện số phiên bản thì bạn đã sẵn sàng. Nếu báo không tìm thấy lệnh, bạn cần cài Node.js trước.

```bash
node --version
npm --version
```

### Cài gói vào dự án của bạn

README chưa ghi một dòng lệnh cài đặt riêng cho người dùng thư viện. Tuy nhiên tên gói npm là `@ai-hero/sandcastle`, nên cách cài phổ thông là lệnh dưới đây. Hãy chạy nó bên trong thư mục dự án (nơi có file `package.json`), không phải ở thư mục bất kỳ.

```bash
npm install @ai-hero/sandcastle
```

Chỗ người mới hay vấp: nếu chưa có dự án, hãy tạo một thư mục mới và chạy `npm init` trước để có `package.json`. Sau đó mới cài gói.

### Đọc phần Getting started và chọn sandbox

Cách khởi tạo cấu hình (trang "Init") và cách gọi `sandcastle.run()` với từng provider được mô tả trong `docs/guide`, không nằm trong README. Mình không chép lệnh ở đây để tránh sai với phiên bản bạn đang dùng. Hãy mở trang Getting started, Sandbox providers và Init trong repo, hoặc xem bản web ở aihero.dev/sandcastle.

Gợi ý chọn sandbox cho người mới: nếu bạn dùng macOS hay Linux/WSL2 thì thử sandbox gốc của hệ điều hành trước vì ít phải cài thêm. Nếu máy đã có Docker thì provider Docker cũng là lựa chọn dễ hiểu.

### (Tuỳ chọn) Cài từ mã nguồn để phát triển

Phần này dành cho người muốn sửa thư viện hoặc đóng góp. Clone repo, vào thư mục rồi chạy các lệnh có trong README:

```bash
git clone https://github.com/mattpocock/sandcastle.git
cd sandcastle
npm install
npm run build    # Bundle with tsup
npm test         # Run tests with vitest
npm run typecheck # Type-check
```

`npm install` tải các thư viện phụ thuộc. `npm run build` đóng gói code bằng tsup. `npm test` chạy bộ test bằng vitest. `npm run typecheck` kiểm tra kiểu TypeScript. Nếu bạn chỉ muốn dùng thư viện, không cần làm bước này.

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

README không nêu một lệnh "hello world" hay kết quả mẫu cho người dùng cuối. Bạn có thể kiểm tra theo các cách sau:

- Sau khi cài gói, mở `package.json` trong dự án của bạn. Nếu thấy `@ai-hero/sandcastle` trong phần dependencies thì gói đã được cài.
- Chạy theo ví dụ trong trang quick start của tài liệu. Dấu hiệu thành công là một lần `sandcastle.run()` chạy xong và để lại commit trên nhánh theo chiến lược nhánh bạn chọn. Bạn kiểm tra bằng `git log`.
- Nếu cài từ mã nguồn, hãy chạy `npm test` và `npm run typecheck`. Cả hai kết thúc không báo lỗi nghĩa là bản build ổn.

Mặt Log chạy (Run logs) cũng được tài liệu mô tả. Đó là nơi để xem agent đã làm gì trong sandbox.

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

README mô tả khả năng ở mức tổng quan, nên các tình huống dưới đây bám đúng những gì thư viện nói là làm được. Chi tiết cách gọi hàm bạn xem trong `docs/guide`.

### Dev cá nhân giao việc lặt vặt cho agent buổi tối

Bạn là lập trình viên tự do, cuối ngày còn vài việc nhỏ như sửa lỗi chính tả trong giao diện, thêm test cho một hàm, đổi tên biến. Bạn viết một script TypeScript gọi `sandcastle.run()` với yêu cầu tương ứng, rồi đi ăn tối. Agent làm việc trong sandbox, không chạm vào thư mục làm việc chính của bạn. Sáng hôm sau bạn xem các commit trên nhánh và quyết định giữ hay bỏ.

> Giao việc cho AI không đáng sợ khi nó làm trong sandbox và để lại commit để bạn duyệt.
>
> — Ông T

### Chạy song song nhiều agent cho nhiều việc độc lập

Đội của bạn có ba việc không liên quan nhau: cập nhật tài liệu, sửa một lỗi nhỏ, thêm một tính năng nhỏ. Thay vì làm lần lượt, bạn gọi nhiều lần `sandcastle.run()` để mỗi agent có sandbox và nhánh riêng. README nêu rõ việc song song hoá nhiều agent AFK là một trường hợp dùng chính. Kết quả là ba nhánh có commit riêng, bạn review từng nhánh.

### Dựng pipeline review code bằng agent

Bạn muốn mọi thay đổi do agent viết đều có người (hoặc agent) đọc lại. Bạn viết một quy trình hai bước: agent thứ nhất viết code, agent thứ hai xem lại thay đổi và nêu nhận xét. README gọi đây là review pipeline. Phần Structured output và Iterations trong tài liệu sẽ giúp bạn lấy kết quả có cấu trúc và lặp lại vòng làm việc.

### Tự viết provider cho hạ tầng sẵn có của công ty

Công ty bạn có hạ tầng chạy riêng và không muốn dùng đám mây có sẵn. README cho biết bạn có thể tạo provider riêng. Dev trong đội dựa vào trang Sandbox providers và `createSandbox()` để cắm hạ tầng của mình vào, còn phần điều phối nhánh và gộp commit vẫn do Sandcastle lo.

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

README không có mục xử lý sự cố. Các lỗi dưới đây là những tình huống rất dễ gặp với loại công cụ này.

### Lệnh npm báo không tìm thấy hoặc không có package.json

Nguyên nhân thường là bạn mở terminal sai thư mục. Hãy dùng `cd` vào đúng thư mục dự án, kiểm tra bằng lệnh liệt kê file xem có `package.json` chưa. Nếu chưa, tạo dự án bằng `npm init` rồi cài lại.

### Sandbox không khởi động được

Với sandbox Docker hoặc Podman, lỗi hay gặp là Docker chưa bật. Hãy mở Docker Desktop (hoặc dịch vụ Podman) và thử lại. Với Bubblewrap, bạn cần đang ở Linux hoặc WSL2, còn Seatbelt chỉ có trên macOS. Chạy nhầm provider với hệ điều hành là nguyên nhân phổ biến.

### Agent không chạy vì thiếu đăng nhập hoặc API key

Agent AI thường cần thông tin xác thực. Nếu agent báo lỗi xác thực, hãy xem trang Agent providers trong tài liệu để biết agent bạn dùng cần gì và cách đưa vào sandbox. Không dán key trực tiếp vào code rồi commit.

### Commit của agent không như mong đợi hoặc xung đột khi gộp

Nếu nhiều agent sửa cùng một file, việc gộp về có thể xung đột. Hãy giao cho mỗi agent phạm vi việc tách bạch, và xem trang Branch strategies để chọn chiến lược nhánh phù hợp. Luôn xem `git log` và `git diff` trước khi đưa thay đổi vào nhánh chính.

### Build hoặc test lỗi khi cài từ mã nguồn

Thường do phiên bản Node không khớp hoặc quên chạy `npm install` trước. Hãy kiểm tra trường engines trong `package.json` (nếu có), cài lại thư viện phụ thuộc, rồi chạy lại `npm run build`.

## Có nên dùng không

Điểm mạnh: ý tưởng gọn (một hàm `run()`), cô lập agent rõ ràng, quản lý nhánh Git tự động, và nhiều lựa chọn sandbox từ máy cá nhân đến đám mây. Giấy phép MIT nên dùng trong dự án thương mại khá thoải mái. Repo có nhiều sao, vẫn được cập nhật, và có bộ tài liệu theo từng khái niệm.

Giới hạn: đây là thư viện cho người viết code, không phải ứng dụng bấm là chạy. Bạn cần biết TypeScript và Git ở mức cơ bản. README ngắn, phần lớn hướng dẫn nằm trong `docs/guide`, nên bạn phải đọc thêm. Chi phí AI và chi phí đám mây (nếu dùng) là phần bạn tự chịu.

Khi nào nên chọn cách khác: nếu bạn không viết code và chỉ cần một trợ lý AI trò chuyện, thư viện này quá nặng. Nếu bạn chỉ cần chạy một agent một lần trên máy mình và không lo về cô lập, dùng thẳng công cụ của agent sẽ đơn giản hơn. Sandcastle phát huy khi bạn muốn tự động hoá, chạy song song và cần ranh giới an toàn.

## 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 miễn phí sử dụng. Tuy nhiên agent AI và các dịch vụ sandbox đám mây (Daytona, E2B, Fly.io Sprites, Modal, Vercel) có thể tính phí riêng. Tư liệu chưa nêu mức giá cụ thể.

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

README nhắc sandbox gốc dùng Bubblewrap trên Linux và WSL2, Seatbelt trên macOS, ngoài ra còn Docker, Podman và các provider đám mây. Vì vậy trên Windows bạn có thể dùng WSL2 hoặc Docker. Tư liệu chưa nói rõ việc chạy thẳng trên Windows không qua WSL2.

### Có cần GPU không?

Tư liệu không nêu yêu cầu GPU. Sandcastle là thư viện điều phối agent nên phần nặng thường nằm ở dịch vụ AI mà agent gọi tới. Yêu cầu phần cứng cụ thể chưa có trong tư liệu.

### Code của tôi có an toàn không khi để agent chạy?

Mục đích của Sandcastle là chạy agent trong sandbox cô lập và cho agent làm trên nhánh riêng, rồi gộp commit về. Điều này giúp hạn chế việc agent tác động trực tiếp lên máy và nhánh chính của bạn. Mức bảo vệ cụ thể phụ thuộc vào loại sandbox bạn chọn, nên hãy đọc trang Sandbox providers trước.

### Sandcastle dùng được với agent nào?

README nói thư viện không phụ thuộc vào một provider cố định và có phần Agent providers trong tài liệu. Tên các agent được hỗ trợ không có trong phần README mình có, nên bạn xem trang Agent providers trong docs/guide.

### Cài bằng cách nào?

Gói npm có tên @ai-hero/sandcastle, nên bạn cài bằng npm install @ai-hero/sandcastle trong dự án của mình. Nếu muốn làm việc trên mã nguồn, clone repo rồi chạy npm install, npm run build. Cách khởi tạo và cấu hình chi tiết nằm trong tài liệu Getting started và Init.

### Sandcastle khác gì việc tự chạy agent trong Docker?

Docker chỉ là một trong nhiều provider mà Sandcastle hỗ trợ. Thư viện thêm phần điều phối: gọi bằng sandcastle.run(), quản lý nhánh và gộp commit về. Tư liệu chưa có so sánh trực tiếp chi tiết với cách tự dựng.
