Skip to main content

​
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

# 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

# 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

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"
The --agents claude flag automatically installs @anthropic-ai/claude-code globally — no manual npm install needed.
Create .caged.yaml in your repo root: 
# .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: 
caged up

​
Option 3: API (Programmatic)

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

Network allowlist: Restrict the sandbox to only the hosts Claude Code needs. This prevents exfiltration if the agent behaves unexpectedly.
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.
Snapshot before risky changes: Run caged snapshot create cage-a1b2c3d4 --name "pre-refactor" before telling Claude to make big changes. You can always restore.

​
More Examples

​
Clone Private Repo with Token

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

​
Python Project with Aider

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

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

​
Interactive Session (No Agent)

# 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!"