Quickstart

Get an AI agent running in an isolated sandbox in 3 steps.

brew tap caged-dev/tap
brew install caged

curl -fsSL https://get.caged.dev | sh

go install github.com/caged-dev/cli/cmd/caged@latest

Verify the installation:

caged version
# caged v0.1.0 (linux/amd64)

caged login
# Enter your API URL and API key

Alternatively, set the CAGED_API_KEY environment variable — useful in CI/CD.

export CAGED_API_KEY=caged_...

Option A: Quick start with flags

caged sandboxes create --template node --cpus 2 --memory 1024

Option B: Config-as-code (recommended for teams)

Create a .caged.yaml in your project root:

template: node    # Alias for node-22 (or use python, minimal, etc.)
resources:
cpu: 2
memory: 1024
disk: 10
timeout: 1800
budget: 5.00
init_script: npm install
env:
NODE_ENV: development

Then just run:

caged up

The CLI reads .caged.yaml automatically — no flags needed.

What Happens Next

Sandboxes boot in ~300ms using Firecracker microVMs. Each gets its own Linux kernel — full OS-level isolation.

A Firecracker microVM boots with your chosen template
Your repo is cloned into /workspace
The init_script runs (e.g., npm install)
The sandbox is ready for your agent

# Output from `caged up`:
✓ Sandbox created: cage-a1b2c3d4
  Status:   running
  Template: node-20
  IP:       10.0.1.42
  Budget:   $5.00

→ Connect: caged connect cage-a1b2c3d4
→ Dashboard: https://caged.dev/sandboxes/cage-a1b2c3d4

Connect to Your Sandbox

# Interactive terminal
caged connect cage-a1b2c3d4

# Or run a single command
caged exec cage-a1b2c3d4 -- npm test

Monitor in the Dashboard

Open caged.dev/dashboard to see:

Live terminal — watch what the agent is doing
File browser — see files as they change
Cost tracker — real-time spend in dollars
Trust score — behavioral safety rating
Preview URLs — click to see web apps the agent builds

Clean Up

# Pause (stop billing, keep state)
caged sleep cage-a1b2c3d4

# Resume later
caged wake cage-a1b2c3d4

# Destroy permanently
caged destroy cage-a1b2c3d4

Next Steps

Understand sandboxes, sessions, and trust scores

Full .caged.yaml reference

Connect Claude Code, Cursor, and other agents

All CLI commands