Sandcage

Run AI coding agents in isolated Docker containers — your machine stays yours.

---

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.

---

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.

Quick Start

Prerequisites: Docker (running) and a Rust toolchain (cargo).

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

# Build the container image
sandcage build

# Run Claude Code in the current project
sandcage claude

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

Usage

sandcage claude                   # Claude Code agent
sandcage codex                    # Codex agent
sandcage gemini                   # Gemini CLI agent
sandcage shell                    # interactive shell, same environment
sandcage claude -p ~/project      # run in a specific project
sandcage claude -- --resume       # forward args to the agent
sandcage claude --shell           # shell for debugging
sandcage build                    # build/rebuild container image
sandcage init                     # generate .sandcage.yml for your project
sandcage setup ssh                # configure SSH key access for containers
sandcage acp run claude           # ACP relay mode (bidirectional stdio)
sandcage acp list                 # list agents in the ACP registry
sandcage acp install <agent-id>   # install an agent from the registry
sandcage acp installed            # list locally installed agents

How It Works

1. You run sandcage claude from your project directory
2. Sandcage resolves the workspace, loads layered config, and generates a compose definition
3. Your project, persistent home, and (optionally) SSH keys are mounted into the container
4. The agent runs as the container entrypoint, working in the mounted workspace
5. All file changes are immediately visible on your host

ACP Support

Sandcage includes built-in support for the Agent Control Protocol (ACP). Running sandcage acp run <service> starts the named agent container and establishes a bidirectional stdio relay, letting any ACP-compatible client communicate with the agent over standard I/O. Agents can be installed from the ACP registry with sandcage acp install <agent-id> and browsed with sandcage acp list.

Configuration

Configuration is layered — each level overrides the one below:

Layer	File	Format
Global	~/.sandcage/config.toml	TOML
Project	.sandcage.yml	YAML
Local	.sandcage.local.yml	YAML

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

# .sandcage.yml — minimal example
toolchains:
  node: "20"
packages:
  - ripgrep
services:
  gemini:
    enabled: false

See Configuration Reference for all available options.

Documentation

Document	Description
Configuration Reference	All config fields, merge behavior, and examples
Command Reference	Every subcommand, flag, and usage pattern
Interactive Mode	How terminal sessions work, backend selection, and Windows compatibility
Architecture	Isolation model, UID/GID mapping, and container design
Docker Image	Base image contents, building, custom Dockerfiles
SSH Key Access	Setting up SSH for git inside containers

Planned Features

• Support for custom harnesses — bring your own agent runtime beyond the built-in Claude Code, Codex, and Gemini CLI
• Full encapsulation hardening — for worker and CI environments, ensuring complete sandboxing of file system, network, and credentials

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