Skip to main content

​
Quickstart

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

Install the CLI

brew install caged-dev/tap/caged
Verify the installation:
caged version
# caged v0.1.0 (linux/amd64)
2

Authenticate

Sign up at caged.dev, then log in:
caged login
# Opens browser for authentication
Alternatively, set the CAGED_API_KEY environment variable — useful in CI/CD.
export CAGED_API_KEY=caged_sk_...
3

Create a Sandbox

Option A: Quick start with flags
caged up --template node-20 --cpus 2 --memory 1024
Option B: Config-as-code (recommended for teams)Create a .caged.yaml in your project root:
.caged.yaml
template: node-20
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.
  1. A Firecracker microVM boots with your chosen template
  2. Your repo is cloned into /workspace
  3. The init_script runs (e.g., npm install)
  4. 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

Concepts

Understand sandboxes, sessions, and trust scores

Config-as-Code

Full .caged.yaml reference

Agent Setup

Connect Claude Code, Cursor, and other agents

CLI Reference

All CLI commands