> ## Documentation Index
> Fetch the complete documentation index at: https://docs.caged.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Running Agents

> How to run AI coding agents inside Caged sandboxes.

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

```bash theme={null}
# 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`:

```yaml theme={null}
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`           |

<Note>
  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.
</Note>

## Manual Agent Setup

### Claude Code

[Claude Code](https://docs.anthropic.com/en/docs/claude-code) is Anthropic's agentic coding tool.

```bash theme={null}
# 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

```yaml theme={null}
# .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](https://aider.chat) works directly in the terminal.

```bash theme={null}
caged connect cage-a1b2c3d4
# Inside sandbox:
pip install aider-chat
aider
```

### Recommended Config

```yaml theme={null}
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:

```bash theme={null}
# 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:

```bash theme={null}
# 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.