CLI Commands

The Caged CLI organizes commands into groups. The main sandbox management commands are under caged sandboxes, with shortcut aliases available for convenience. Authenticate with your Caged account via browser.

caged login

Opens your browser to caged.dev/auth/device where you approve the CLI access. The CLI automatically receives your credentials once approved — no manual key copying needed.

$ caged login
Logging in to Caged...

  Your code: ABCD-EFGH

  Opening browser to: https://caged.dev/auth/device?code=ABCD-EFGH

  Waiting for authorization...

  Logged in as [email protected]
  Credentials saved to ~/.config/caged/config.json

If you prefer to paste an API key directly (CI environments, headless servers):

caged login --manual

Prompts for your API URL and API key interactively. Stores credentials at ~/.config/caged/config.json.

caged up

Create a sandbox from .caged.yaml in the current directory.

caged up [flags]

Flag	Description	Default
`--template`	Override base image	from config
`--cpus`	Override vCPU count	from config
`--memory`	Override memory in MB	from config
`--disk`	Override disk in GB	from config
`--repo`	Git repo URL to clone	—
`--repo-token`	PAT/OAuth token for private repos	—
`--repo-branch`	Branch to checkout	main
`--repo-commit`	Specific commit SHA	—
`--repo-subdir`	Monorepo subdirectory to extract	—
`--budget`	Max spend in USD	—
`--network`	Network mode: full, none, allowlist	from config
`--allowlist`	Comma-separated host allowlist	—
`--env`	Environment variables (KEY=VAL,KEY2=VAL2)	—
`--packages`	Packages to pre-install (comma-separated)	—
`--agents`	AI agents to install (claude, aider, codex)	—
`--config`	Path to config file	`.caged.yaml`

Examples:

# From .caged.yaml in current directory
caged up

# Override template and budget
caged up --template python-312 --budget 10

# Clone a private repo with Claude Code
caged up --template node-20 \
  --repo https://github.com/your-org/private-repo \
  --repo-token $GITHUB_TOKEN \
  --agents claude

# Clone a specific branch
caged up --repo https://github.com/user/project --repo-branch develop

# With custom config file
caged up --config ./sandbox.yaml

caged sandboxes

The sandboxes command group manages sandbox lifecycle.

caged sandboxes list

List all sandboxes. Alias: caged list, caged ls.

caged sandboxes list [flags]

Flag	Description	Default
`--format`	Output format: `table`, `json`	`table`

Examples:

caged sandboxes list
caged sandboxes list --format json

Table output:

ID              STATUS    TEMPLATE     CPUs  MEMORY   CREATED
cage_abc123     running   node-20      2     1024MB   2024-01-15T10:30:00Z
cage_def456     sleeping  python-3.12  4     2048MB   2024-01-14T08:00:00Z

JSON output:

[
  {
    "id": "cage_abc123",
    "status": "running",
    "template": "node-20",
    "cpus": 2,
    "memory_mb": 1024,
    "created_at": "2024-01-15T10:30:00Z"
  }
]

caged sandboxes create

Create and start a new sandbox. Alias: caged run.

caged sandboxes create [flags]

Flag	Description	Default
`--template`	Base image	`node-20`
`--cpus`	vCPU count	`2`
`--memory`	Memory in MB	`512`
`--disk`	Disk in GB	`5`
`--network`	Network mode: full, none, allowlist	`full`
`--allowlist`	Comma-separated host allowlist	—
`--repo`	Git repo to clone	—
`--env`	Environment variables (KEY=VAL,KEY2=VAL2)	—
`--budget`	Max spend in USD	—

Examples:

caged sandboxes create --template node-20 --cpus 2 --memory 1024
caged sandboxes create --template python-3.12 --budget 5 --repo https://github.com/user/project
caged sandboxes create --network allowlist --allowlist "registry.npmjs.org,github.com"

caged sandboxes connect

Connect to a running sandbox’s interactive terminal. Alias: caged connect.

caged sandboxes connect <sandbox-id>

Opens a full interactive terminal (real PTY over WebSocket) — like ssh into the sandbox. Output streams live, so long-running commands and AI agents show their progress in real time. Arrow keys, tab completion, Ctrl+C, colors, and terminal resizing all work.

Connected to sandbox cage_abc123 (node-20). Type 'exit' or press Ctrl+D to disconnect.
root@caged-sandbox:~# npm test
✓ All tests passed
root@caged-sandbox:~# exit

For non-interactive/scripted use, prefer caged exec.

caged sandboxes exec

Execute a single command in a sandbox and return the output. Alias: caged exec.

caged sandboxes exec <sandbox-id> <command>

Examples:

caged sandboxes exec cage_abc123 "npm test"
caged sandboxes exec cage_abc123 "cat package.json"
caged sandboxes exec cage_abc123 "git status"

caged sandboxes sleep

Pause a running sandbox. No compute charges while sleeping. Alias: caged sleep.

caged sandboxes sleep <sandbox-id>

caged sandboxes wake

Resume a sleeping sandbox. Alias: caged wake.

caged sandboxes wake <sandbox-id>

caged sandboxes destroy

Destroy a sandbox permanently. Alias: caged destroy, caged rm.

caged sandboxes destroy <sandbox-id>

caged sandboxes logs

View sandbox event logs. Alias: caged logs.

caged sandboxes logs <sandbox-id> [flags]

Flag	Description
`-f`	Follow log output in real-time

caged sandboxes logs cage_abc123
caged sandboxes logs -f cage_abc123

caged mcp

Run a Model Context Protocol server over stdio, bridged to a running sandbox. MCP clients like Claude Desktop and Cursor spawn this command locally — no WebSocket setup or session tokens required.

caged mcp <sandbox-id>

Add it to your MCP client configuration:

{
  "mcpServers": {
    "caged": {
      "command": "caged",
      "args": ["mcp", "cage_abc123"]
    }
  }
}

The AI client gets sandbox tools (filesystem_read, filesystem_write, terminal_exec, git_commit, and more) that execute inside the isolated VM. The sandbox must be running — wake it with caged wake <sandbox-id> first if it’s sleeping.

caged version

Print CLI version.

caged version

Shortcut Aliases

For convenience, sandbox commands have shortcuts at the top level:

Shortcut	Equivalent
`caged list`	`caged sandboxes list`
`caged ls`	`caged sandboxes list`
`caged run`	`caged sandboxes create`
`caged connect <id>`	`caged sandboxes connect <id>`
`caged exec <id> <cmd>`	`caged sandboxes exec <id> <cmd>`
`caged destroy <id>`	`caged sandboxes destroy <id>`
`caged rm <id>`	`caged sandboxes destroy <id>`
`caged sleep <id>`	`caged sandboxes sleep <id>`
`caged wake <id>`	`caged sandboxes wake <id>`
`caged logs <id>`	`caged sandboxes logs <id>`

These shortcuts are provided for backward compatibility and convenience. Both forms work identically.

caged policy

Manage security policies (Cage Rules).

caged policy list

List all policies for your account.

caged policy list

caged policy templates

Show available policy templates.

caged policy templates

caged policy apply

Apply a built-in template to your account.

caged policy apply <template>

Templates: soc2, hipaa, dev-only, restrictive, permissive

caged policy delete

Delete a policy by ID.

caged policy delete <policy-id>

caged eval

Manage agent eval scenarios and runs (Cage Eval).

caged eval list

List all eval scenarios.

caged eval list

caged eval load

Load scenarios from a YAML file. Supports suite files (.caged-eval.yaml) and single scenario files (*.scenario.yaml).

caged eval load <file.yaml>

caged eval discover

Find eval scenario files in a directory.

caged eval discover [directory]

caged eval run

Run a specific scenario.

caged eval run <scenario-id>

caged eval flakiness

Run a scenario multiple times to detect flakiness.

caged eval flakiness <scenario-id> [--iterations 10]

caged eval regression

Detect performance regression against baseline runs.

caged eval regression <scenario-id>

caged eval runs

List run history for a scenario.

caged eval runs <scenario-id>

caged eval delete

Delete a scenario.

caged eval delete <scenario-id>

​CLI Commands

​caged login

​Manual login (API key)

​caged up

​caged sandboxes

​caged sandboxes list

​caged sandboxes create

​caged sandboxes connect

​caged sandboxes exec

​caged sandboxes sleep

​caged sandboxes wake

​caged sandboxes destroy

​caged sandboxes logs

​caged mcp

​caged version

​Shortcut Aliases

​caged policy

​caged policy list

​caged policy templates

​caged policy apply

​caged policy delete

​caged eval

​caged eval list

​caged eval load

​caged eval discover

​caged eval run

​caged eval flakiness

​caged eval regression

​caged eval runs

​caged eval delete

CLI Commands

caged login

Manual login (API key)

caged up

caged sandboxes

caged sandboxes list

caged sandboxes create

caged sandboxes connect

caged sandboxes exec

caged sandboxes sleep

caged sandboxes wake

caged sandboxes destroy

caged sandboxes logs

caged mcp

caged version

Shortcut Aliases

caged policy

caged policy list

caged policy templates

caged policy apply

caged policy delete

caged eval

caged eval list

caged eval load

caged eval discover

caged eval run

caged eval flakiness

caged eval regression

caged eval runs

caged eval delete