Sandcastle
A TypeScript library for orchestrating AI coding agents in isolated sandboxes.
- GitHub stars
- 8,525
- npm downloads a week
- 57,227
npm install --save-dev @ai-hero/sandcastleimport { 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 providerpromptFile: ".sandcastle/prompt.md",});
How it works
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.
Sandbox providers
- Docker
@ai-hero/Bind-mountsandcastle/ sandboxes/ docker - Podman
@ai-hero/Bind-mountsandcastle/ sandboxes/ podman - Vercel
@ai-hero/Isolatedsandcastle/ sandboxes/ vercel - No-sandbox
@ai-hero/Nonesandcastle/ sandboxes/ no-sandbox - Custom providersBind-mount when the sandbox can mount a host directory. Isolated when it has its own filesystem.
Documentation
Start here
Guides
- Sandbox providersSandcastle uses a SandboxProvider to create isolated environments.
- How it worksSandcastle uses a branch strategy configured on the sandbox provider to control how the agent's changes relate to branches.
- PromptsSandcastle uses a flexible prompt system.
- ConfigurationAll per-repo sandbox configuration lives in .sandcastle/.
Reference
- APISandcastle exports a programmatic run() function for use in scripts, CI pipelines, or custom tooling.
- CLI commandsScaffolds the .sandcastle/ config directory and builds the container image.
- Custom sandbox providersSandcastle ships with built-in providers for Docker, Podman, and Vercel, but you can create your own.