Caution

⚠️ Unreleased Software ⚠️

🚧 This project is under active development and not yet released. APIs, configuration formats, and behavior may change without notice. Please do not use without contacting the author about the current state of the project. 🚧

Warning

⚠️ Development Tool Only ⚠️

🚧 Sandcage is designed for local development use. Do not use it in CI pipelines or production environments — container isolation is not yet hardened for those contexts. 🚧

Planned Features

Full encapsulation hardening — for worker and CI environments, ensuring complete sandboxing of file system, network, and credentials
ACP integration via dirigate — Agent Communication Protocol support for structured agent orchestration

Why Sandcage?

AI coding agents need broad access to do their work: shell, filesystem, network. Letting them run directly on your machine means they share your credentials, your session history, and your entire environment.

Sandcage gives each agent its own container with the tools it needs. Your project is mounted in, changes are visible on the host, but the agent never touches your shell config, your SSH agent, or anything else outside the sandbox.

Multiple agents can run side by side. A persistent home directory means config and credentials survive between sessions, so you are not re-authenticating every time.

How It Works

You run sandcage claude (or codex, or shell) from your project directory
Sandcage resolves your workspace to the git root and builds Docker compose arguments
Your project, persistent home, and (optionally) SSH keys are mounted into the container
The agent runs as the container entrypoint, working in the mounted workspace
All file changes are immediately visible on your host

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

Build images and run

sandcage build           # build base and codex images
sandcage claude           # start Claude Code in the current project

That is it. Sandcage resolves your project to its git root, mounts it into the container, and drops you into the agent.

More commands

sandcage claude -p ~/project         # run in a specific project
sandcage claude -- --resume          # forward args to the agent
sandcage codex -p ~/project          # run Codex instead
sandcage shell                        # interactive shell, same environment
sandcage claude --shell              # shell in the Claude image (debugging)
sandcage init                         # detect ecosystem, generate .sandcage.yml
sandcage setup ssh                    # configure SSH key mounting
sandcage setup ssh --global          # configure SSH globally

Configuration

Configuration is layered. Each level overrides the one below it, so you only set what you need:

Compiled defaults — sensible out of the box Global config (~/.sandcage/config.toml) — user-wide preferences Project config (.sandcage.yml) — per-project setup, checked into version control Local config (.sandcage.local.yml) — personal overrides, gitignored (SSH keys, secrets, local mounts) CLI flags — per-invocation overrides

.sandcage.yml example

packages:
  - ripgrep
  - fd-find
toolchains:
  rust: stable
  node: "20"
env:
  DATABASE_URL: "postgres://localhost:5432/dev"
mounts:
  - ~/.ssh:/home/agent/.ssh:ro
agent_args:
  claude:
    - --dangerously-skip-permissions
shell: zsh

Run sandcage init to generate a starter config — it detects your project ecosystem (Rust, Node, Python, Go) and suggests appropriate toolchains and packages.

Docker Image

Sandcage uses a single image (sandcage) based on Debian bookworm-slim, packed with dev tools: git, openssh-client, ripgrep, fd, jq, curl, zsh, bash, sudo, just, and uv.

AI agents (Claude Code, Codex) are installed on first run into the persistent home directory and auto-update themselves — no agent binaries baked into the image.

Build with sandcage build. Use --force to rebuild unconditionally.

Cross-Platform

Sandcage works on Linux, macOS, and Windows (PowerShell, cmd, and Git Bash). On Windows with WSL, it works from both the Windows and Linux sides.

License

MIT