# sandcastle

> TypeScript library that runs AI coding agents in isolated sandboxes, then merges commits

- Repository: https://github.com/mattpocock/sandcastle
- Category: Coding agents & dev tools
- Stars: 8,601 · Forks: 917 · Language: TypeScript · License: MIT
- Experience: Some experience
- Page: https://ir.adyog.com/repos/mattpocock/sandcastle/

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.

## Who it's for

Developers comfortable with TypeScript, git and Docker who want to automate coding agents; you also need a Claude token or Anthropic API key.

## 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/sandcastle
```
```
npx @ai-hero/sandcastle init
```
```
npx tsx .sandcastle/main.ts
```

Tags: coding-agents, sandbox, typescript, docker, orchestration