mattpocock/sandcastle

What it solves

Sandcastle provides a secure and automated way to run AI coding agents in isolated environments. It prevents agents from having unrestricted access to your host machine while automating the tedious parts of the development cycle, such as creating git branches, managing sandboxes, and merging changes back into the main codebase.

How it works

The library orchestrates the lifecycle of an AI agent's work. When a user invokes an agent, Sandcastle creates an isolated sandbox (using providers like Docker, Podman, or Vercel) and assigns a specific git branch strategy. The agent performs its coding tasks within this sandbox; once finished, Sandcastle collects the commits made by the agent and merges them back to the host repository.

Who it’s for

It is designed for developers building AI-powered coding workflows, such as parallelized agentic tasks, automated code review pipelines, or custom orchestration tools for coding agents.

Highlights

• Provider-Agnostic Sandboxing: Built-in support for Docker, Podman, and Vercel, with the ability to create custom providers.
• Branch Management: Automatically handles branch creation and merging of agent-generated commits.
• Flexible Execution: Supports one-shot runs via run() or reusable, warm sandboxes via createSandbox() to avoid repeated container startup costs.
• Lifecycle Hooks: Allows running custom shell commands on both the host and inside the sandbox during setup.
• Programmable API: Offers a TypeScript API for integration into CI pipelines and scripts, including support for structured output extraction.