Guides
View as Markdown Open in ChatGPT Open in Claude

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

# .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.

  1. Create a sandbox: caged up --template node-20
  2. Get SSH details: caged ssh-config cage-a1b2c3d4
  3. Add to ~/.ssh/config
  4. 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

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.

Was this page helpful?