---
title: "Sandcastle integration"
description: "Run Claude Code or Codex in parallel E2B sandboxes with Sandcastle's built-in E2B provider, and get the agents' commits back in your local repo."
url: "https://e2b.dev/integrations/sandcastle"
---

# Sandcastle

> Sandcastle runs coding agents like Claude Code and Codex on your repo, each in its own E2B sandbox. The agents' commits come back to a branch on your machine.

Coding agents · [All integrations](https://e2b.dev/integrations.md)

## About this integration

- **Maintained by:** Sandcastle
- **How it works:** Built-in E2B sandbox provider
- **Package:** @ai-hero/sandcastle
- **Language:** TypeScript
- **Upstream:** [mattpocock/sandcastle · ★ 9.2k](https://github.com/mattpocock/sandcastle)
- **Example:** [e2b-cookbook/sandcastle-parallel-agents-js](https://github.com/e2b-dev/e2b-cookbook/tree/main/examples/sandcastle-parallel-agents-js)

## Get started

Paste the prompt into your coding agent, or follow the steps yourself.

### Paste this into your coding agent

```text
Add E2B sandboxes to this Sandcastle project.

1. Install @ai-hero/sandcastle and e2b using the project's package manager.
2. Sandcastle needs the E2B_API_KEY environment variable in my shell. If it isn't set, ask me for my API key from https://console.e2b.dev/?tab=keys. Never hardcode it, and never put it in .sandcastle/.env.
3. Follow the Sandcastle guide at https://docs.e2b.dev/agents/sandcastle and run claudeCode with sandbox: e2b({ template: "claude" }), passing ANTHROPIC_API_KEY in the agent env.
4. Run it once from the repo root and show me the commits that came back from the sandbox.
```

## Or set it up yourself

### 1. Install Sandcastle and E2B

```bash
npm install @ai-hero/sandcastle e2b
```

### 2. Set your API keys

```bash
export E2B_API_KEY="e2b_..."
export ANTHROPIC_API_KEY="..."
```

### 3. Run Claude Code in a sandbox

```typescript
import { run, claudeCode } from "@ai-hero/sandcastle";
import { e2b } from "@ai-hero/sandcastle/sandboxes/e2b";

const result = await run({
  agent: claudeCode("claude-opus-4-8", {
    env: { ANTHROPIC_API_KEY: process.env.ANTHROPIC_API_KEY! },
  }),
  sandbox: e2b({ template: "claude" }),
  prompt: "Fix the failing test in src/slugify.js and commit the fix.",
});

console.log(result.commits);
```

## What runs in the sandbox

Each agent works on a copy of your repo in its own sandbox. Only its commits come back.

- **Code:** The agent CLI from the template, claude or codex, working on a copy of your repo in $HOME/workspace.
- **Commits:** Commits land on your current branch, or on a separate one with branchStrategy.
- **Lifetime:** run() creates a sandbox and kills it when the run finishes. At timeoutMs, 30 minutes by default, it's killed, never paused.
- **Secrets:** Only keys in .sandcastle/.env and the providers' env reach the sandbox. Keep E2B_API_KEY out of .sandcastle/.env.

## More coding agents

Other coding agents that run in E2B sandboxes.

- [Claude Code](https://e2b.dev/integrations/claude-code.md): Run Claude Code in its own sandbox with a real filesystem, terminal, and git, so it can work unattended.
- [OpenAI Codex](https://e2b.dev/integrations/codex.md): Run OpenAI's Codex CLI headless in a sandbox and collect the diff when it's done.
- [OpenCode](https://e2b.dev/integrations/opencode.md): Run OpenCode in a sandbox, or keep it local and point its workspaces at E2B with the @e2b/opencode plugin.

## Links

- [Get API key](https://console.e2b.dev/?tab=keys)
- [Read the docs](https://docs.e2b.dev/agents/sandcastle)
- [E2B documentation](https://docs.e2b.dev)
