This TypeScript library, Sandcastle, enables the orchestration of AI coding agents within isolated Docker containers. It simplifies complex agent workflows by managing worktrees, sandboxing execution, and merging agent-generated commits back to the host repository. Sandcastle is ideal for developers seeking to parallelize AI tasks, build automated code review pipelines, or integrate custom AI agents into their development process, offering a robust and localized execution environment.

How It Works

Sandcastle employs a worktree-based architecture. It creates isolated Git worktrees on the host machine, which are then bind-mounted into Docker containers. This direct host filesystem access means agents write changes immediately to the host, eliminating the need for file synchronization. Commits made by the agent within the worktree are automatically fast-forward merged back to a specified target branch upon completion, and the worktree is cleaned up, providing a seamless integration with standard Git workflows.

Quick Start & Requirements

• Installation: npm install @ai-hero/sandcastle
• Initialization: Run npx sandcastle init . to scaffold the .sandcastle/ directory and Docker image.
• Configuration: Set API keys (e.g., ANTHROPIC_API_KEY) in .sandcastle/.env.
• Execution: Use npx tsx .sandcastle/main.ts or the programmatic API (import { run } from "@ai-hero/sandcastle").
• Prerequisites: Docker Desktop, Git.
• Documentation: API and usage details are extensively documented within the README.

Highlighted Details

• Programmatic API: Offers a run() function for integration into scripts, CI/CD pipelines, and custom tooling, with extensive configuration options for agents, prompts, worktree modes, hooks, and logging.
• Reusable Sandboxes: createSandbox() allows multiple agent runs within a single, persistent container and worktree, optimizing performance by avoiding repeated setup costs and maintaining state across runs.
• Flexible Prompting: Supports inline prompts, prompt files, dynamic context injection via !commandexecution within the sandbox, and{{KEY}}placeholder substitution viapromptArgs. Includes built-in {{SOURCE_BRANCH}}and{{TARGET_BRANCH}}` arguments.
• Workflow Templates: sandcastle init scaffolds projects using templates like blank, simple-loop, sequential-reviewer, and parallel-planner to accelerate setup for common agent-based workflows.
• Early Termination: Agents can signal completion using a configurable completionSignal (defaulting to <promise>COMPLETE</promise>), allowing for task-based workflows where the agent stops execution once its objective is met.

Maintenance & Community

No specific details regarding maintainers, community channels (like Discord/Slack), or roadmap were provided in the README.

Licensing & Compatibility

The project is released under the MIT License, which permits commercial use and integration into closed-source projects without significant restrictions.

Limitations & Caveats

Requires Docker Desktop and Git to be installed and configured. Agent providers necessitate corresponding API keys (e.g., ANTHROPIC_API_KEY). Customizing the Dockerfile requires careful attention to maintain essential dependencies and the non-root user configuration. The sandcastle init command prevents overwriting existing .sandcastle/ configurations, requiring manual merging or deletion for updates.