Sandcastle is a TypeScript library designed for orchestrating AI coding agents in isolated sandbox environments. The core functionality revolves around a single `sandcastle.run()` function that invokes agents within configurable sandboxed branches, automatically handling the sandbox lifecycle and merging commits back to the host repository. The library is provider-agnostic, shipping with built-in support for Docker, Podman, and Vercel's Firecracker microVMs, while also allowing developers to create custom sandbox providers.
The repository has grown steadily, reaching 6622 stargazers as of the latest tracking period. GitGenius data shows strong community engagement with a median issue and pull request response latency of just 0.1 hours, though the mean response time is 21.4 hours across 591 tracked items. The most active issue labels are ready-for-agent with 171 items, enhancement with 132 items, and bug with 46 items, indicating an active development cycle focused on feature expansion and stability improvements. Matt Pocock, the repository creator, dominates contributor activity with 1988 tracked events, while secondary contributors mtsdlf and Yibeibankaishui have 16 and 12 events respectively.
Sandcastle's architecture supports multiple usage patterns. The `run()` function handles one-shot agent invocations with automatic sandbox lifecycle management, while `createSandbox()` enables reusable sandbox instances for running multiple agents or multiple rounds sequentially within the same container. This design avoids repeated container startup costs and allows dependencies and build artifacts to persist across runs. The library also provides `sandbox.exec()` for running shell commands directly within the sandbox, useful for verification steps before triggering review processes.
The sandbox provider system is central to Sandcastle's flexibility. Built-in providers include Docker for local bind-mount sandboxing, Podman as a rootless Docker alternative, Vercel for cloud-based isolated environments, and a no-sandbox option for running agents directly on the host when container isolation is unnecessary. Developers can implement custom providers using `createBindMountSandboxProvider` or `createIsolatedSandboxProvider` for specialized use cases.
Configuration options are extensive and granular. The `SandboxRunOptions` interface allows developers to specify agent providers, inline prompts or prompt files with placeholder substitution, iteration limits, completion signals, idle and completion timeouts, logging preferences, and session resumption capabilities. The library supports AbortSignal for cancellation and includes lifecycle hooks for both host and sandbox environments. Results from runs include per-iteration details, matched completion signals, combined stdout output, created commits, and optional log file paths.
Advanced features include session resumption and forking capabilities. The `resume()` method allows agents that support session capture to continue from a prior state within the same warm sandbox, while `fork()` creates a branching continuation without modifying the parent session. The `createWorktree()` function provides independent git worktree lifecycle management, useful when running interactive sessions before handing off to sandboxed agents.
The repository is classified across multiple domains including TypeScript, documentation, code examples, interactive playground, API reference, developer tools, tutorials, code snippets, and learning platform. This breadth reflects Sandcastle's positioning as both a production library and an educational resource. Related repositories with overlapping contributors include mattpocock/course-video-manager, mattpocock/evalite, and anomalyco/opencode, suggesting an ecosystem of complementary tools for AI agent orchestration and evaluation.
