---
title: Run Claude Code on a Repo
description: "Spin up an isolated sandbox and let Claude Code work on your project autonomously."
---

# Run Claude Code on a Repo

This recipe creates a sandbox, clones your repository, installs Claude Code, and lets it work autonomously — all within a budget-controlled, isolated environment.

## Prerequisites

- Caged CLI installed (`brew install caged-dev/tap/caged` or `curl -fsSL https://get.caged.dev | sh`)
- Caged account with API key (`caged login`)
- An `ANTHROPIC_API_KEY` stored in your Caged secrets

## Quick Start Examples

### Basic: Sandbox with Claude Code

```bash
# Create sandbox with Claude Code pre-installed
caged up --template node-20 --agents claude

# Connect to the sandbox
caged connect cage_xxxxx

# Inside the sandbox, Claude is ready
caged> claude "What files are in this directory?"
```

### Clone a Repo + Claude Code

```bash
# Clone your repo and install Claude Code
caged up \
  --template node-20 \
  --repo https://github.com/your-org/your-project \
  --agents claude

# Connect and start working
caged connect cage_xxxxx
caged> claude "Review this codebase and suggest improvements"
```

### Full Example with All Options

```bash
caged up \
  --template node-20 \
  --cpus 2 \
  --memory 2048 \
  --repo https://github.com/your-org/your-project \
  --budget 10 \
  --agents claude \
  --env "ANTHROPIC_API_KEY=$ANTHROPIC_API_KEY"
```

<Tip>
The `--agents claude` flag automatically installs `@anthropic-ai/claude-code` globally — no manual npm install needed.
</Tip>

## Option 2: Config File (Recommended for Teams)

Create `.caged.yaml` in your repo root:

```yaml
# .caged.yaml
template: node-20
resources:
  cpu: 2
  memory: 2048
  disk: 10
timeout: 3600        # Auto-sleep after 1 hour idle
budget: 10.00        # Hard limit: $10

repo: https://github.com/your-org/your-project

agents:
  - claude           # Auto-installs Claude Code (alias for claude-code)

secrets:
  - ANTHROPIC_API_KEY

init_script: |
  npm install

network_mode: allowlist
allowed_hosts:
  - api.anthropic.com
  - registry.npmjs.org
  - github.com
```

Then run:

```bash
caged up
```

## Option 3: API (Programmatic)

```bash
# Create the sandbox with Claude Code pre-installed
SANDBOX_ID=$(curl -s -X POST https://api.caged.dev/v1/sandboxes \
  -H "Authorization: Bearer caged_sk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "template": "node-20",
    "cpus": 2,
    "memory_mb": 2048,
    "disk_gb": 10,
    "repo": "https://github.com/your-org/your-project",
    "budget": 10.00,
    "agents": ["claude-code"],
    "secrets": ["ANTHROPIC_API_KEY"]
  }' | jq -r '.id')

echo "Sandbox created: $SANDBOX_ID"

# Execute Claude Code inside the sandbox
curl -X POST "https://api.caged.dev/v1/sandboxes/$SANDBOX_ID/exec" \
  -H "Authorization: Bearer caged_sk_..." \
  -d '{"command": "claude \"Fix all lint errors and add missing tests\""}'
```

## Monitoring Progress

While Claude Code is running:

```bash
# Watch live logs
caged logs cage-a1b2c3d4 --follow

# Check current cost
caged list
```

```
ID               TEMPLATE   STATUS    COST      BUDGET    UPTIME
cage-a1b2c3d4    node-20    running   $2.34     $10.00    15m
```

## Tips

<Tip>
**Network allowlist**: Restrict the sandbox to only the hosts Claude Code needs. This prevents exfiltration if the agent behaves unexpectedly.
</Tip>

<Tip>
**Budget as guardrail**: Set a budget slightly above what you expect the task to cost. The sandbox is terminated if the budget is reached, preventing runaway token usage.
</Tip>

<Tip>
**Snapshot before risky changes**: Run `caged snapshot create cage-a1b2c3d4 --name "pre-refactor"` before telling Claude to make big changes. You can always restore.
</Tip>

## More Examples

### Clone Private Repo with Token

```bash
caged up \
  --template node-20 \
  --repo https://github.com/your-org/private-repo \
  --repo-token $GITHUB_TOKEN \
  --agents claude
```

### Python Project with Aider

```bash
caged up \
  --template python-312 \
  --repo https://github.com/your-org/python-project \
  --agents aider \
  --env "OPENAI_API_KEY=$OPENAI_API_KEY"
```

### Install Dependencies First

```bash
caged up \
  --template node-20 \
  --repo https://github.com/your-org/your-project \
  --init "npm install" \
  --agents claude
```

### Interactive Session (No Agent)

```bash
# Just get a shell in the sandbox
caged up --template node-20
caged connect cage_xxxxx

# Install tools manually
caged> npm install -g @anthropic-ai/claude-code
caged> claude "Hello!"
```