5.0 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 |
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
# 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 |
Trailing arguments: Any arguments after -- are forwarded directly to the Codex binary inside the container.
Examples:
# Run Codex on the current directory
sandcage codex
# 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 |
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
# 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) |
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.yml configuration file for a project.
sandcage init
Scaffolds a project configuration in the current workspace directory. No options.
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
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.