435 lines
9.4 KiB
Markdown
435 lines
9.4 KiB
Markdown
# Command Reference
|
|
|
|
Sandcage provides subcommands for running AI coding agents in isolated Docker containers.
|
|
|
|
```
|
|
sandcage <COMMAND> [OPTIONS]
|
|
```
|
|
|
|
---
|
|
|
|
## claude
|
|
|
|
Run the Claude Code agent in a sandboxed container.
|
|
|
|
```
|
|
sandcage claude [OPTIONS] [-- AGENT_ARGS...]
|
|
```
|
|
|
|
**Options:**
|
|
|
|
| Flag | Description |
|
|
|------|-------------|
|
|
| `-p, --path <PATH>` | Path to the project directory (defaults to current directory) |
|
|
| `--shell` | Drop into a shell instead of launching the agent |
|
|
| `--worktree` | Create a git worktree and mount it instead of the project directory |
|
|
| `--home <NAME>` | Named home profile for agent auth/config (default: "default") |
|
|
|
|
**Trailing arguments:** Any arguments after `--` are forwarded directly to the Claude Code binary inside the container.
|
|
|
|
**Examples:**
|
|
|
|
```sh
|
|
# Run Claude Code on the current directory
|
|
sandcage claude
|
|
|
|
# Run Claude Code on a specific project
|
|
sandcage claude --path /home/user/myproject
|
|
|
|
# Drop into a shell in the Claude container environment
|
|
sandcage claude --shell
|
|
|
|
# Run in a disposable worktree copy
|
|
sandcage claude --worktree
|
|
|
|
# Run with a specific home profile (e.g. work account)
|
|
sandcage claude --home work
|
|
|
|
# Forward arguments to the agent
|
|
sandcage claude -- --resume
|
|
```
|
|
|
|
---
|
|
|
|
## codex
|
|
|
|
Run the OpenAI Codex agent in a sandboxed container.
|
|
|
|
```
|
|
sandcage codex [OPTIONS] [-- AGENT_ARGS...]
|
|
```
|
|
|
|
**Options:**
|
|
|
|
| Flag | Description |
|
|
|------|-------------|
|
|
| `-p, --path <PATH>` | Path to the project directory (defaults to current directory) |
|
|
| `--shell` | Drop into a shell instead of launching the agent |
|
|
| `--worktree` | Create a git worktree and mount it instead of the project directory |
|
|
| `--home <NAME>` | Named home profile for agent auth/config (default: "default") |
|
|
|
|
**Trailing arguments:** Any arguments after `--` are forwarded directly to the Codex binary inside the container.
|
|
|
|
**Examples:**
|
|
|
|
```sh
|
|
# Run Codex on the current directory
|
|
sandcage codex
|
|
|
|
# Run Codex in a disposable worktree
|
|
sandcage codex --worktree
|
|
|
|
# Forward arguments to Codex
|
|
sandcage codex -- --model o4-mini
|
|
```
|
|
|
|
---
|
|
|
|
## gemini
|
|
|
|
Run the Gemini CLI agent in a sandboxed container.
|
|
|
|
```
|
|
sandcage gemini [OPTIONS] [-- AGENT_ARGS...]
|
|
```
|
|
|
|
**Options:**
|
|
|
|
| Flag | Description |
|
|
|------|-------------|
|
|
| `-p, --path <PATH>` | Path to the project directory (defaults to current directory) |
|
|
| `--shell` | Drop into a shell instead of launching the agent |
|
|
| `--worktree` | Create a git worktree and mount it instead of the project directory |
|
|
| `--home <NAME>` | Named home profile for agent auth/config (default: "default") |
|
|
|
|
**Trailing arguments:** Any arguments after `--` are forwarded directly to the Gemini CLI binary inside the container.
|
|
|
|
**Examples:**
|
|
|
|
```sh
|
|
# Run Gemini CLI on the current directory
|
|
sandcage gemini
|
|
|
|
# Run Gemini in a disposable worktree
|
|
sandcage gemini --worktree
|
|
|
|
# Drop into a shell in the Gemini container
|
|
sandcage gemini --shell
|
|
```
|
|
|
|
---
|
|
|
|
## shell
|
|
|
|
Open an interactive shell (zsh) with the same sandboxed environment used by agents.
|
|
|
|
```
|
|
sandcage shell [OPTIONS]
|
|
```
|
|
|
|
**Options:**
|
|
|
|
| Flag | Description |
|
|
|------|-------------|
|
|
| `-p, --path <PATH>` | Path to the project directory (defaults to current directory) |
|
|
| `--home <NAME>` | Named home profile for agent auth/config (default: "default") |
|
|
|
|
**Examples:**
|
|
|
|
```sh
|
|
# Interactive shell in the sandbox for current project
|
|
sandcage shell
|
|
|
|
# Interactive shell for a specific project
|
|
sandcage shell --path /home/user/myproject
|
|
```
|
|
|
|
---
|
|
|
|
## build
|
|
|
|
Build the container images used by sandcage services.
|
|
|
|
```
|
|
sandcage build [OPTIONS] [SERVICES...]
|
|
```
|
|
|
|
**Options:**
|
|
|
|
| Flag | Description |
|
|
|------|-------------|
|
|
| `-f, --force` | Force rebuild even if images are up to date |
|
|
|
|
**Positional arguments:** Optionally specify which services to build (e.g. `claude`, `codex`, `gemini`). When omitted, all enabled services are built.
|
|
|
|
**Examples:**
|
|
|
|
```sh
|
|
# Build all enabled service images
|
|
sandcage build
|
|
|
|
# Force rebuild of all images
|
|
sandcage build --force
|
|
|
|
# Build only the claude image
|
|
sandcage build claude
|
|
|
|
# Build claude and gemini images
|
|
sandcage build claude gemini
|
|
```
|
|
|
|
---
|
|
|
|
## init
|
|
|
|
Initialize a `.sandcage/` directory with configuration for a project.
|
|
|
|
```
|
|
sandcage init
|
|
```
|
|
|
|
Scaffolds a `.sandcage/` directory in the current workspace with `sandcage.yml`, `overlay/`, `local/`, `local/overlay/`, and a `.gitignore` that excludes `local/`.
|
|
|
|
Refuses to run from linked git worktrees — run it from the main worktree instead.
|
|
|
|
**Examples:**
|
|
|
|
```sh
|
|
# Initialize sandcage config in current directory
|
|
sandcage init
|
|
```
|
|
|
|
---
|
|
|
|
## setup ssh
|
|
|
|
Configure SSH key access for containers. Copies selected SSH keys into a Docker volume accessible by sandcage containers.
|
|
|
|
```
|
|
sandcage setup ssh [OPTIONS]
|
|
```
|
|
|
|
**Options:**
|
|
|
|
| Flag | Description |
|
|
|------|-------------|
|
|
| `--global` | Write to global config (`~/.sandcage/config.toml`) instead of project config |
|
|
| `--yes` | Skip confirmation prompt |
|
|
| `--refresh` | Re-populate the SSH volume using the previously saved selection |
|
|
| `--bind` | Use legacy full bind mount instead of volume copy |
|
|
|
|
**Examples:**
|
|
|
|
```sh
|
|
# Interactive SSH key setup for the current project
|
|
sandcage setup ssh
|
|
|
|
# Non-interactive setup writing to global config
|
|
sandcage setup ssh --global --yes
|
|
|
|
# Refresh the SSH volume after adding new keys
|
|
sandcage setup ssh --refresh
|
|
```
|
|
|
|
---
|
|
|
|
## acp
|
|
|
|
Manage and run ACP (Agent Control Protocol) agents. This command group requires the `bollard` feature, which is enabled by default.
|
|
|
|
```
|
|
sandcage acp <SUBCOMMAND>
|
|
```
|
|
|
|
---
|
|
|
|
### acp run
|
|
|
|
Run a service in ACP relay mode, attaching stdin/stdout/stderr for bidirectional communication with the container. Uses the Bollard Docker API directly instead of docker compose. Designed for structured agent orchestration.
|
|
|
|
```
|
|
sandcage acp run <SERVICE> [OPTIONS] [-- AGENT_ARGS...]
|
|
```
|
|
|
|
**Options:**
|
|
|
|
| Flag | Description |
|
|
|------|-------------|
|
|
| `-p, --path <PATH>` | Path to the project directory (defaults to current directory) |
|
|
|
|
**Positional arguments:** `<SERVICE>` — the service name to run (e.g. `claude`, `codex`).
|
|
|
|
**Trailing arguments:** Any arguments after `--` are forwarded directly to the agent binary inside the container.
|
|
|
|
**Examples:**
|
|
|
|
```sh
|
|
# Run the claude service in ACP relay mode
|
|
sandcage acp run claude
|
|
|
|
# Run against a specific project directory
|
|
sandcage acp run claude --path /home/user/myproject
|
|
|
|
# Forward arguments to the agent
|
|
sandcage acp run claude -- --resume
|
|
```
|
|
|
|
---
|
|
|
|
### acp install
|
|
|
|
Install an agent from the ACP registry. Downloads the agent binary for the current platform and caches it at `~/.sandcage/agents/<id>/<version>/`.
|
|
|
|
```
|
|
sandcage acp install <AGENT_ID> [OPTIONS]
|
|
```
|
|
|
|
**Options:**
|
|
|
|
| Flag | Description |
|
|
|------|-------------|
|
|
| `--force` | Reinstall even if the agent is already installed |
|
|
|
|
**Positional arguments:** `<AGENT_ID>` — the identifier of the agent to install from the registry.
|
|
|
|
**Examples:**
|
|
|
|
```sh
|
|
# Install an agent from the registry
|
|
sandcage acp install my-agent
|
|
|
|
# Force reinstall an already-installed agent
|
|
sandcage acp install my-agent --force
|
|
```
|
|
|
|
---
|
|
|
|
### acp list
|
|
|
|
List available agents in the ACP registry. Fetches the agent list from the CDN with a 1-hour local cache.
|
|
|
|
```
|
|
sandcage acp list [OPTIONS]
|
|
```
|
|
|
|
**Options:**
|
|
|
|
| Flag | Description |
|
|
|------|-------------|
|
|
| `--refresh` | Bypass the local cache and fetch a fresh list from the registry |
|
|
|
|
**Examples:**
|
|
|
|
```sh
|
|
# List available agents (uses cache if fresh)
|
|
sandcage acp list
|
|
|
|
# Force a fresh fetch from the registry
|
|
sandcage acp list --refresh
|
|
```
|
|
|
|
---
|
|
|
|
### acp installed
|
|
|
|
List locally installed ACP agents.
|
|
|
|
```
|
|
sandcage acp installed
|
|
```
|
|
|
|
No options.
|
|
|
|
**Examples:**
|
|
|
|
```sh
|
|
# Show all locally installed ACP agents
|
|
sandcage acp installed
|
|
```
|
|
|
|
---
|
|
|
|
## clean
|
|
|
|
Remove shadow volumes for the current project. By default runs a dry run showing what would be removed.
|
|
|
|
```
|
|
sandcage clean [OPTIONS]
|
|
```
|
|
|
|
**Options:**
|
|
|
|
| Flag | Description |
|
|
|------|-------------|
|
|
| `--yes` | Actually delete (default is a dry run) |
|
|
|
|
**Examples:**
|
|
|
|
```sh
|
|
# Preview what would be removed
|
|
sandcage clean
|
|
|
|
# Remove shadow volumes
|
|
sandcage clean --yes
|
|
```
|
|
|
|
---
|
|
|
|
## worktree
|
|
|
|
Manage sandcage-created git worktrees. Worktrees are created under `~/.sandcage/worktrees/`.
|
|
|
|
---
|
|
|
|
### worktree list
|
|
|
|
List all sandcage-managed worktrees.
|
|
|
|
```
|
|
sandcage worktree list
|
|
```
|
|
|
|
**Examples:**
|
|
|
|
```sh
|
|
sandcage worktree list
|
|
```
|
|
|
|
---
|
|
|
|
### worktree clean
|
|
|
|
Remove all sandcage-managed worktrees.
|
|
|
|
```
|
|
sandcage worktree clean [OPTIONS]
|
|
```
|
|
|
|
**Options:**
|
|
|
|
| Flag | Description |
|
|
|------|-------------|
|
|
| `--yes` | Skip confirmation prompt |
|
|
|
|
**Examples:**
|
|
|
|
```sh
|
|
# Interactive cleanup
|
|
sandcage worktree clean
|
|
|
|
# Non-interactive cleanup
|
|
sandcage worktree clean --yes
|
|
```
|
|
|
|
---
|
|
|
|
## Common Patterns
|
|
|
|
**Project path resolution:** All agent commands and `shell` accept `--path` (`-p`) to specify the project directory. When omitted, sandcage resolves the workspace from the current directory.
|
|
|
|
**Shell override:** The `--shell` flag on agent commands (`claude`, `codex`, `gemini`) drops you into an interactive shell inside the agent's container without launching the agent itself. Useful for debugging the container environment.
|
|
|
|
**Forwarding arguments to agents:** Agent commands accept trailing arguments (after `--`) that are passed through to the underlying agent binary. This allows setting agent-specific flags without sandcage needing to know about them.
|
|
|
|
**Available services:** The built-in services are `claude`, `codex`, `gemini`, and `shell`. Each agent service auto-installs its binary on first run if not already present in the container.
|