134 lines
4.9 KiB
Markdown
134 lines
4.9 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>
|
|
|
|
---
|
|
|
|
> [!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.
|
|
|
|
<!-- TODO: Terminal demo
|
|
Recording tool: https://github.com/charmbracelet/vhs
|
|
Will show: sandcage build → sandcage claude → agent working → exit
|
|
Place animated GIF or SVG here once recorded.
|
|
-->
|
|
|
|
## Quick Start
|
|
|
|
**Prerequisites:** Docker (running) and a Rust toolchain (cargo).
|
|
|
|
```bash
|
|
# 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
|
|
```
|
|
|
|
## 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` 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
|
|
|
|
## Configuration
|
|
|
|
<p align="center">
|
|
<img src="config-layers.svg" alt="Configuration layering — defaults, global, project, local, CLI flags" width="720">
|
|
</p>
|
|
|
|
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.
|
|
|
|
```yaml
|
|
# .sandcage.yml — minimal example
|
|
toolchains:
|
|
node: "20"
|
|
packages:
|
|
- ripgrep
|
|
services:
|
|
gemini:
|
|
enabled: false
|
|
```
|
|
|
|
See **[Configuration Reference](docs/configuration.md)** for all available options.
|
|
|
|
## Documentation
|
|
|
|
| Document | Description |
|
|
|----------|-------------|
|
|
| [Configuration Reference](docs/configuration.md) | All config fields, merge behavior, and examples |
|
|
| [Command Reference](docs/commands.md) | Every subcommand, flag, and usage pattern |
|
|
| [Docker Image](docs/docker-image.md) | Base image contents, building, custom Dockerfiles |
|
|
| [SSH Key Access](docs/ssh.md) | 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
|
|
- **ACP integration** via [`dirigate`](https://github.com/dirigence/dirigate) — Agent Communication Protocol support for structured agent orchestration
|
|
|
|
## 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
|