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

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

License

MIT