AIHero

    Sandcastle

    A TypeScript library for orchestrating AI coding agents, tools such as Claude Code or Codex that read and change your code on their own. Each agent runs in an isolated sandbox: a container, a VM or an OS process sandbox that limits what the agent can reach, so you can leave it to work.

    GitHub stars
    9,081
    npm downloads a week
    215,504
    Get startedView on GitHub
    npm install --save-dev @ai-hero/sandcastle
    import { run, claudeCode } from "@ai-hero/sandcastle";

    import { bwrap } from "@ai-hero/sandcastle/sandboxes/bwrap";

    

    await run({

      agent: claudeCode("claude-opus-4-8"),

      sandbox: bwrap(), // seatbelt() on macOS, or docker(), podman(), vercel(), or your own provider

      promptFile: ".sandcastle/prompt.md",

    });

    How it works

    1. You invoke agents with a single sandcastle.run().

    2. Sandcastle handles sandboxing the agent with a configurable [branch strategy](/sandcastle/glossary#branch-strategy), which decides where the agent's commits go: onto your current branch, onto a temporary branch it merges back for you, or onto a branch you name.

    3. The commits made on the branches get merged back.

    Branch strategies

    Sandbox providers

    • Bubblewrap@ai-hero/sandcastle/sandboxes/bwrapNative (bind-mount)
    • Seatbelt@ai-hero/sandcastle/sandboxes/seatbeltNative (bind-mount)
    • Docker@ai-hero/sandcastle/sandboxes/dockerBind-mount
    • Podman@ai-hero/sandcastle/sandboxes/podmanBind-mount
    • E2B@ai-hero/sandcastle/sandboxes/e2bIsolated
    • Modal@ai-hero/sandcastle/sandboxes/modalIsolated
    • Sprites@ai-hero/sandcastle/sandboxes/spritesIsolated
    • Vercel@ai-hero/sandcastle/sandboxes/vercelIsolated
    • No-sandbox@ai-hero/sandcastle/sandboxes/no-sandboxNone
    • Custom providersBind-mount when the sandbox can mount a host directory. Isolated when it has its own filesystem.
    Compare providers

    Documentation

    Start here

    Concepts

    Running

    Reference

    MIT