mattpocock /
sandcastle
TypeScript library that runs AI coding agents in isolated sandboxes, then merges commits
- 8.6k stars
- 384 stars since 3 Oct
- TypeScript
- Updated 2 days ago
- Some experience
- Coding agents & dev tools
Coding agents work best when left alone for a while, but running them directly on your computer is risky. Sandcastle gives you a function, run(), that starts an agent in an isolated environment, lets it work on a branch, and brings its commits back to your repository.
You pick an agent (the README shows Claude Code), a sandbox provider, and a prompt, either inline or from a file. The agent loops up to a set number of iterations and stops early when it prints a completion signal. The result lists the commits made and the branch used.
It is a library, not a hosted service or chat app. You write ordinary TypeScript to chain steps, such as an implement run followed by a review run in the same warm sandbox. Docker and Podman use bind mounts, Vercel uses cloud microVMs, and you can write your own provider.
What it does
One-call agent runs
run() starts an agent in a sandbox and returns the iterations, commits and branch name. It takes an inline prompt or a prompt file, with {{KEY}} placeholders filled from promptArgs.
Swappable sandbox providers
Built-in providers cover Docker, Podman and Vercel. You can write your own, or use noSandbox() to run on the host directly.
Branch strategies
You choose how the agent's changes relate to branches, such as committing to HEAD or to a named branch like agent/fix-42. The commits are merged back afterwards.
Reusable sandbox for multi-step flows
createSandbox() keeps one container alive across several run() calls, so installed dependencies persist. sandbox.exec() runs shell commands in it, for example to check work before a review step.
Logging and lifecycle controls
Hooks run on the host or in the sandbox, and timeouts are configurable. Logs go to a file or stdout, and you can forward the agent's output stream to your own tooling.
What you could build
- Run several coding agents in parallel on separate branches while you are away from the keyboard.
- Build an implement-then-review pipeline where one model writes a fix and another reviews it.
- Script an agent to fix a numbered issue in CI and collect the resulting commits.
- Write a custom sandbox provider to run agents in your own isolated environment.
- Extract a typed result from an agent's output using the structured output option.
Get started
Install the package, then run the init command to scaffold a .sandcastle directory. Copy the example .env file, add your Claude token or Anthropic API key, and run .sandcastle/main.ts with tsx. Docker, Podman or Vercel must be available as the sandbox.
npm install --save-dev @ai-hero/sandcastlenpx @ai-hero/sandcastle initnpx tsx .sandcastle/main.tsCommands are copied from the project's README. Read it on GitHub for the full setup.
More in Coding agents & dev tools
rea
MCP server that lets AI agents reverse engineer apps, binaries and websites locally
opencode
Open source AI coding agent for your terminal, with a beta desktop app
claude-code
Terminal coding assistant that reads your codebase and takes plain-English commands
codex
A coding agent from OpenAI that runs in your terminal on your own machine
pi
A minimal terminal coding agent you extend with skills, extensions and packages
orca
Desktop and mobile app for running many coding agents side by side
Understand-Anything
Turns a codebase or wiki into an interactive graph you can search and ask questions about
screenshot-to-code
Turns screenshots, mockups and screen recordings into front-end code with AI models
warp
Rust terminal that adds a built-in coding agent and runs other CLI agents
free-claude-code
Local proxy that lets Claude Code, Codex, Aider and others run on free or cheap models