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

Install

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

Or from a local checkout:

cargo install --path crates/sandcage

Build the images

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

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

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)

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