9.4 KiB
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:
# 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:
# 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:
# 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:
# 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:
# 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:
# 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:
# 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:
# 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:
# 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:
# 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:
# 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:
# 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:
sandcage worktree list
worktree clean
Remove all sandcage-managed worktrees.
sandcage worktree clean [OPTIONS]
Options:
| Flag | Description |
|---|---|
--yes |
Skip confirmation prompt |
Examples:
# 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.