# 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 để đ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.

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

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.

```repo
- repo | mattpocock/sandcastle
- kind | Thư viện
- desc | 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.
- stars | 9k
- lang | TypeScript
- license | MIT
```

## 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.

## 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.

```note
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.
```

## 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.

```steps
- Mở terminal | Mở đúng thư mục dự án (hoặc thư mục sẽ chứa mã nguồn)
- Lấy mã nguồn | Dùng git clone để tải repo về máy
- Cài phụ thuộc | Chạy npm install
- Build | Chạy npm run build để đóng gói bằng tsup
- Kiểm tra | Chạy npm test và npm run typecheck
```

### 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.

### 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.

```bash
git clone https://github.com/mattpocock/sandcastle.git
cd sandcastle
```

### 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.

```bash
npm install
```

### Build thư viện

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

```bash
npm run build
```

### 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.

```bash
npm test
npm run typecheck
```

### 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à:

```bash
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.

## 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.

## 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()`.

### 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

### 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.

### 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.

### 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.

## 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ô.

## 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.

## 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.
