117 lines
4.0 KiB
Markdown
117 lines
4.0 KiB
Markdown
<p align="center">
|
|
<img src="sandcage_logo.png" width="120" alt="Sandcage">
|
|
</p>
|
|
|
|
<h1 align="center">Sandcage</h1>
|
|
|
|
<p align="center">
|
|
Run AI coding agents in isolated Docker containers — your machine stays yours.
|
|
</p>
|
|
|
|
---
|
|
|
|
## 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
|
|
|
|
<p align="center">
|
|
<img src="topology.svg" alt="Sandcage topology — host, Docker, container, volume mounts" width="720">
|
|
</p>
|
|
|
|
1. You run `sandcage claude` (or `codex`, or `shell`) from your project directory
|
|
2. Sandcage resolves your workspace to the git root and builds Docker compose arguments
|
|
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
|
|
|
|
## 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
|
|
```
|
|
|
|
### Build images and run
|
|
|
|
```bash
|
|
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
|
|
|
|
<p align="center">
|
|
<img src="config-layers.svg" alt="Configuration layering — defaults, global, project, CLI flags" width="720">
|
|
</p>
|
|
|
|
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
|
|
**CLI flags** — per-invocation overrides
|
|
|
|
### .sandcage.yml example
|
|
|
|
```yaml
|
|
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
|