sandcage-export
92 lines
2.7 KiB
Markdown
92 lines
2.7 KiB
Markdown
# 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
|