<div align="center" <picture <source media="(prefers-color-scheme: dark)" srcset="https://res.cloudinary.com/total-typescript/image/upload/v1775033787/readme-sandcastle-ondark2x.png" <source media="(prefers-color-scheme: light)" srcset="https://res.cloudinary.com/total-typescript/image/upload/v1775033787/readme-sandcastle-onlight2x.png" <img alt="Sandcastle" src="https://res.cloudinary.com/total-typescript/image/upload/v1775033787/readme-sandcastle-onlight2x.png" height="200" style="margin-bottom: 20px;" </picture </div
What Is Sandcastle?
A TypeScript library for orchestrating AI coding agents in isolated sandboxes:
- You invoke agents with a single sandcastle.run().
- Sandcastle handles sandboxing the agent with a configurable branch strategy.
- The commits made on the branches get merged back.
Sandcastle is provider-agnostic — it ships with built-in providers for Docker, Podman, and Vercel, and you can create your own. Great for parallelizing multiple AFK agents, creating review pipelines, or even just orchestrating your own agents.
Prerequisites
- Git
- A sandbox provider — Sandcastle needs an isolated environment to run agents in. Built-in options:
- Docker Desktop — most common for local development
- Podman — rootless alternative to Docker
- Vercel — cloud-based Firecracker microVMs via @vercel/sandbox
- Or create your own using createBindMountSandboxProvider or createIsolatedSandboxProvider
Quick start
- Install the package:
npm install --save-dev @ai-hero/sandcastle- Run npx @ai-hero/sandcastle init. This scaffolds a .sandcastle directory with all the files needed.
npx @ai-hero/sandcastle init- Edit .sandcastle/.env and fill in your default values for CLAUDECODEOAUTHTOKEN (run claude setup-token on your host to get one). To use an Anthropic API key instead, uncomment and fill in ANTHROPICAPIKEY.
cp .sandcastle/.env.example .sandcastle/.env- Run the .sandcastle/main.ts (or main.mts) file with npx tsx
npx tsx .sandcastle/main.ts// 3. Run the agent via the JS API
import { run, claudeCode } from "@ai-hero/sandcastle";
import { docker } from "@ai-hero/sandcastle/sandboxes/docker";
await run({
agent: claudeCode("claude-opus-4-8"),
sandbox: docker(), // or podman(), vercel(), or your own provider
promptFile: ".sandcastle/prompt.md",
});