dirigence/sandcage
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

🛰️ export from upstream (251518c)

Browse Source
This commit is contained in:
Gabor Körber
2026-05-24 19:52:42 +02:00
parent 0cd116aff2
commit 2e0c340768
4 changed files with 631 additions and 88 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+74 -88
View File
@@ -11,20 +11,14 @@
---
> [!CAUTION]
> **⚠️ Unreleased Software ⚠️**
> **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. 🚧
> 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 ⚠️**
> **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
- **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
> 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.
---
@@ -36,107 +30,99 @@ Sandcage gives each agent its own container with the tools it needs. Your projec
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` (or `codex`, `gemini`, or `shell`) from your project directory
2. Sandcage resolves your workspace to the git root and builds Docker compose arguments
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
## 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 container image
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 gemini -p ~/project # run Gemini CLI 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 # select and copy SSH keys for containers
sandcage setup ssh --global # store SSH config globally
sandcage setup ssh --refresh # re-sync keys after changes
```
## 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 it, so you only set what you need:
Configuration is layered — each level overrides the one below:
**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
```yaml
packages:
- ripgrep
- fd-find
toolchains:
rust: stable
node: "20"
env:
DATABASE_URL: "postgres://localhost:5432/dev"
agent_args:
claude:
- --dangerously-skip-permissions
shell: zsh
# Enable/disable built-in services
services:
gemini:
enabled: false
# Control which services `sandcage build` prepares by default
# default_services:
# - claude
# - shell
```
SSH key access is configured separately via `sandcage setup ssh`, which selects only the keys needed for git and copies them into a dedicated Docker volume.
| 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.
## Docker Image
```yaml
# .sandcage.yml — minimal example
toolchains:
node: "20"
packages:
- ripgrep
services:
gemini:
enabled: false
```
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.
See **[Configuration Reference](docs/configuration.md)** for all available options.
AI agents (Claude Code, Codex, Gemini CLI) are installed on first run into the persistent home directory and auto-update themselves — no agent binaries baked into the image.
## Documentation
Build with `sandcage build`. Use `--force` to rebuild unconditionally. You can also specify which services to build: `sandcage build claude codex`.
| 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