mattpocock/sandcastle

What it solves

Sandcastle is a TypeScript library designed to orchestrate AI coding agents in isolated sandboxes. It prevents agents from making uncontrolled changes to your host system by running them in containers, while automating the process of managing git branches and merging changes back into the main codebase.

How it works

Sandcastle uses a SandboxProvider system to create isolated environments. It supports built-in providers for Docker, Podman, and Vercel, and allows for custom provider creation. When an agent is invoked via sandcastle.run(), the library handles the sandboxing, applies a configurable branch strategy to isolate changes, and merges the resulting commits back to the host.

Who it’s for

It is intended for developers building AI-driven coding workflows, such as parallelizing multiple "AFK" agents, creating automated review pipelines, or orchestrating complex multi-agent sequences (e.g., an implementation agent followed by a review agent).

Highlights

• Provider-Agnostic Sandboxing: Built-in support for Docker, Podman, and Vercel, with an option to run without a sandbox for local development.
• Flexible Branching: Configurable strategies to manage how agent changes are committed and merged.
• Reusable Sandboxes: The createSandbox() API allows running multiple agents or iterations within a single warm container to avoid startup overhead.
• Lifecycle Hooks: Supports host and sandbox-side hooks to run setup commands (like npm install) before the agent starts.
• Programmatic Control: Full JS API for integration into scripts, CI pipelines, and custom tooling.