mattpocock /sandcastle

Orchestrate sandboxed coding agents in TypeScript with sandcastle.run()

★ 9,094⑂ 982👁 26⑃ 844● 806▤ 45
TypeScriptMITCreated 2026-03-17
More from this author
Download: v0.14.0v0.14.0 ↓0.14.02026-11-02
+18
Daily
9,094
stars
982
forks
26
watchers
844
prs
806
issues
45
releases

README

What is Sandcastle?

A TypeScript library for orchestrating AI coding agents in isolated sandboxes:

1. You invoke agents with a single sandcastle.run().
2. Sandcastle handles sandboxing the agent with a configurable branch strategy.
3. The commits made on the branches get merged back.

Sandcastle is provider-agnostic. It ships with native sandboxes that use your OS's own process sandbox (Bubblewrap on Linux and WSL2, Seatbelt on macOS), image-based providers for Docker and Podman, and cloud providers for Daytona, E2B, Fly.io Sprites, Modal and Vercel, and you can create your own. Great for parallelizing multiple AFK agents, creating review pipelines, or even just orchestrating your own agents.

 Documentation

The docs live in docs/guide, one page per major term, with every term defined in the Glossary, and are published at aihero.dev/sandcastle.

- Getting started: prerequisites and a quick start
- Core: Core concepts
- Sandboxes: Sandbox providers
- Branching: Branch strategies
- Agents: Agent providers, Agent sessions
- Execution: Iterations, Structured output
- Prompts: Prompts
- Hooks: Hooks
- Init: Init
- Display: Run logs
- Reference: run() and createSandbox(), CLI commands, Glossary

 Development

bash
npm install
npm run build     Bundle with tsup
npm test          Run tests with vitest
npm run typecheck  Type-check


 License

MIT

Top issues

Latest release

v0.14.0 v0.14.0 2026-11-02
Minor Changes

- d99fff8: Add an E2B isolated sandbox provider, e2b() from @ai-hero/sandcastle/sandboxes/e2b. It needs the optional e2b peer dependency and E2B_API_KEY (or the apiKey option). Use a template that ships your agent's CLI, such as e2b({ template: "claude" }).
- 8783573: Add modal(), an isolated sandbox provider for Modal sandboxes, at @ai-hero/sandcastle/sandboxes/modal. Install modal (an optional peer dependency) and set MODAL_TOKEN_ID and MODAL_TOKEN_SECRET, or pass tokenId and tokenSecret. By default it builds a node:24-bookworm image with Claude Code installed; pass image for 

Snapshot: 2026-11-16T09:23:14Z · Data license Apache-2.0 · JSON