Running Agents

Caged supports any AI coding agent that can work inside a Linux terminal. You can either use the built-in --agents flag for automatic setup, or install agents manually.

Quick Start with `--agents`

The easiest way to set up agents is using the --agents flag:

# Create a sandbox with Claude Code pre-installed
caged run --template node-20 --agents claude-code

# Multiple agents at once
caged run --template node-20 --agents claude-code,aider

# With caged up
caged up --agents claude-code,codex

Or in your .caged.yaml:

template: node-20
resources:
  cpu: 2
  memory: 2048
agents:
  - claude-code
  - aider
secrets:
  - ANTHROPIC_API_KEY
  - OPENAI_API_KEY

Supported Agents

Agent	Aliases	Template	Required Env	Run Command
`claude-code`	`claude`	node-22, node-20	`ANTHROPIC_API_KEY`	`claude`
`aider`	-	python-312, python-311	`OPENAI_API_KEY` or `ANTHROPIC_API_KEY`	`aider`
`codex`	`openai`	node-22, node-20	`OPENAI_API_KEY`	`codex`
`chatgpt`	`gpt`	any	(browser auth)	`chatgpt`
`grok`	-	any	`XAI_API_KEY`	`grok`
`cline`	-	node-22, node-20	`ANTHROPIC_API_KEY`	VS Code extension
`continue`	-	node-22, node-20	varies	VS Code extension
`goose`	-	python-312, python-311	`OPENAI_API_KEY`	`goose`
`mentat`	-	python-312, python-311	`OPENAI_API_KEY`	`mentat`
`devika`	-	python-312, python-311	`OPENAI_API_KEY`	`devika`
`sweep`	-	python-312, python-311	`GITHUB_TOKEN`	`sweep`

If required environment variables are missing, the agent will be installed but may not work until you set them. Add secrets to your .caged.yaml or pass --env flags.

Manual Agent Setup

Claude Code

Claude Code is Anthropic’s agentic coding tool.

# Create a sandbox with your repo
caged up --template node-20 --repo https://github.com/user/project

# Connect to the sandbox
caged connect cage-a1b2c3d4

# Inside the sandbox, run Claude Code
claude

Recommended Config

# .caged.yaml
template: node-20
resources:
  cpu: 2
  memory: 2048
timeout: 3600
budget: 10.00
secrets:
  - ANTHROPIC_API_KEY
init_script: npm install -g @anthropic-ai/claude-code

Cursor

Use Cursor’s remote SSH feature to connect to a Caged sandbox.

Create a sandbox: caged up --template node-20
Get SSH details: caged ssh-config cage-a1b2c3d4
Add to ~/.ssh/config
In Cursor: Remote SSH → Connect to Host → cage-a1b2c3d4

Aider

Aider works directly in the terminal.

caged connect cage-a1b2c3d4
# Inside sandbox:
pip install aider-chat
aider

Recommended Config

template: python-312
resources:
  cpu: 2
  memory: 1024
budget: 5.00
secrets:
  - OPENAI_API_KEY
init_script: pip install aider-chat

Custom MCP Agents

Connect any MCP-compatible agent via WebSocket:

# Get the MCP WebSocket URL
curl https://api.caged.dev/v1/sandboxes/cage-a1b2c3d4/mcp \
  -H "Authorization: Bearer caged_sk_..."

The WebSocket endpoint provides:

File read/write tools
Terminal execution tools
Git operations
Environment management

Agent Comparison

Agent	Interface	Best For
Claude Code	Terminal	Autonomous coding tasks
Cursor	IDE (SSH)	Interactive development
Aider	Terminal	Git-integrated pair programming
Custom MCP	WebSocket	Custom workflows

Monitoring Agent Activity

While an agent is running, you can monitor it from the dashboard or CLI:

# Real-time cost tracking
caged status cage-a1b2c3d4

# Stream agent logs
caged logs cage-a1b2c3d4 -f

# View trust score
caged trust cage-a1b2c3d4

All agent actions (file writes, terminal commands, LLM calls) are recorded and visible in the session replay.

Getting Started

Guides

Running Agents

Running Agents

Quick Start with `--agents`

Supported Agents

Manual Agent Setup

Claude Code

Recommended Config

Cursor

Aider

Recommended Config

Custom MCP Agents

Agent Comparison

Monitoring Agent Activity

​Running Agents

​Quick Start with --agents

​Supported Agents

​Manual Agent Setup

​Claude Code

​Recommended Config

​Cursor

​Aider

​Recommended Config

​Custom MCP Agents

​Agent Comparison

​Monitoring Agent Activity

Running Agents

Quick Start with `--agents`

Supported Agents

Manual Agent Setup

Claude Code

Recommended Config

Cursor

Aider

Recommended Config

Custom MCP Agents

Agent Comparison

Monitoring Agent Activity