224 lines
5.0 KiB
Markdown
224 lines
5.0 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 |
|
|
|
|
**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
|
|
|
|
# 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:**
|
|
|
|
```sh
|
|
# 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:**
|
|
|
|
```sh
|
|
# 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:**
|
|
|
|
```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.yml` configuration file for a project.
|
|
|
|
```
|
|
sandcage init
|
|
```
|
|
|
|
Scaffolds a project configuration in the current workspace directory. No options.
|
|
|
|
**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
|
|
```
|
|
|
|
---
|
|
|
|
## 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.
|