mattpocock/sandcastle

What it does

Sandcastle is a TypeScript library for orchestrating AI coding agents inside isolated sandboxes. You call sandcastle.run(); Sandcastle creates the sandbox using a configurable branch strategy, then merges commits made on those branches back. It is provider-agnostic, with native OS process sandboxes (Bubblewrap on Linux/WSL2, Seatbelt on macOS), Docker and Podman image-based providers, and cloud providers including Daytona, E2B, Fly.io Sprites, Modal and Vercel. Custom providers are supported. Typical uses are parallel AFK agents, review pipelines, and managing your own agents README lines 9–18.

Getting started

The official getting started guide is the entry point for prerequisites and a quick start; the full documentation set is indexed in docs/guide, including a glossary that defines the major terms README lines 19–34. The guide is also published at aihero.dev/sandcastle. The README itself does not show the install command or a complete run() example, so follow the getting-started page rather than inferring a call signature. For API details, see run() and createSandbox() and the CLI commands.

Supporting pages cover sandbox providers, branch strategies, agent providers, agent sessions, iterations, structured output, prompts, hooks, init, and run logs.

Development

To work on the library itself, install dependencies, then build, test and type-check README lines 35–43:

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

Constraints

Sandcastle is written in TypeScript and published under the MIT license README lines 44–46. Sandbox behavior depends on the chosen provider: native sandboxes rely on the host OS mechanisms, while Docker, Podman and cloud providers introduce their own runtime and account requirements. Agent behavior depends on the selected agent provider and session configuration. The README does not specify supported TypeScript or Node versions, platform coverage beyond the listed sandbox backends, or cost implications of cloud providers.

HotRepo's take

On the 2026-11-03 TypeScript daily list, Sandcastle recorded 8,802 stars and 941 forks with 28 stars gained that day, placing 12th on that language list. That is a single snapshot rather than a trend series, and no all-language daily rank has been recorded. The technical takeaway is that the abstraction sits at the sandbox-and-branch layer rather than inside any one agent vendor, which is what makes parallel agent runs and review pipelines plausible across providers; the trade-off is that you inherit the setup and cost profile of whichever sandbox and agent provider you pick.