# Sandcage

Sandcage runs AI coding agents (Claude Code, Codex) in isolated Docker containers. Each agent gets a full development environment with your project mounted as a workspace, while your host session and credentials stay private.

## Why

Running AI agents directly on your machine means they share your shell, your credentials, and your session history. Sandcage gives each agent its own container with the tools it needs, while keeping your host environment untouched.

Agents in different containers can still see each other's work through shared sandbox state (~/.sandcage/), enabling session handoffs between agents working on different branches or worktrees.

## Quick Start

### Prerequisites

- Docker (daemon must be running)
- Rust toolchain (cargo) — or download a prebuilt binary from [Releases](https://github.com/dirigence/sandcage/releases)

### Install

```bash
cargo install --git https://github.com/dirigence/sandcage
```

Or from a local checkout:

```bash
cargo install --path crates/sandcage
```

### Build the images

```bash
sandcage build
```

This builds three images: `sandcage-base`, `sandcage-claude`, and `sandcage-codex`. Images whose Dockerfile hasn't changed are skipped automatically. Use `--force` to rebuild unconditionally.

### Run an agent

```bash
sandcage claude                      # Claude Code in current directory
sandcage claude -p ~/project         # Claude Code in a specific project
sandcage claude -- --resume          # forward --resume to Claude Code
sandcage codex -p ~/project          # Codex in a specific project
sandcage shell                       # interactive shell, same environment
sandcage claude --shell              # shell in the Claude image (for debugging)
```

The workspace is resolved to the git repo root automatically. Inside a git worktree, the worktree root is used instead. Arguments after `--` are forwarded to the agent inside the container.

### Initialize a project

```bash
sandcage init
```

Detects the language ecosystem (Rust, Node, Python, Go) and generates a `.sandcage.yml` with suggested configuration.

## Configuration

Configuration is layered: compiled defaults → `~/.sandcage/config.toml` → `.sandcage.yml` → CLI flags

### Project configuration (.sandcage.yml)

```yaml
env:
  DATABASE_URL: "postgres://localhost:5432/dev"
packages:
  - ripgrep
  - fd-find
toolchains:
  rust: "stable"
  node: "20"
mounts:
  - /data/models:/models:ro
shell: zsh
```

## Architecture

### Images (3-tier)

| Image | Base | Adds |
|-------|------|------|
| sandcage-base | Debian bookworm-slim | git, ripgrep, fd, jq, curl, zsh, bash, sudo, just, uv |
| sandcage-claude | sandcage-base | Claude Code CLI |
| sandcage-codex | sandcage-base | Codex binary (multi-arch) |

## License

MIT