---
title: Running Agents
description: "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
# 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
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
# 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
# .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
caged connect cage-a1b2c3d4
# Inside sandbox:
pip install aider-chat
aider
```

### Recommended Config

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