Core Concepts

This page explains the fundamental building blocks of the Caged platform.

New to Caged? Start with the Quickstart to create your first sandbox, then come back here to understand the concepts in depth.

Sandboxes

A sandbox is an isolated Linux environment where an AI agent does its work. Each sandbox is:

• A dedicated Firecracker microVM (production) or Docker container (local dev)
• Has its own kernel, filesystem, and network namespace
• Runs a single agent session at a time
• Billed per-second of compute time

Sandbox Lifecycle

pending → running → paused → running → destroyed
                  ↘ destroyed

State	Description	Billing
pending	VM is booting	No charge
running	Agent is active	Billed per-second
paused	Frozen in memory (sleep)	No charge
destroyed	Permanently removed	No charge

Idle Timeout

Sandboxes auto-sleep after a period of inactivity (default: 15 minutes). Configure this in .caged.yaml:

timeout: 1800  # 30 minutes

Sessions

A session is one agent interaction with a sandbox. It captures:

• Start/end time and duration
• Agent type (Claude Code, Cursor, Aider, etc.)
• Total tokens in/out
• LLM cost + compute cost
• Trust score
• All events (commands, file changes, LLM calls)

Sessions are created when an agent connects and end when it disconnects.

Trust Scores

Every session gets a trust score (0–100) based on agent behavior:

Score	Rating	Meaning
90–100	Excellent	Standard development, no risky actions
70–89	Good	Minor concerns (large file deletes, etc.)
50–69	Caution	Suspicious patterns detected
0–49	Alert	Dangerous behavior (network exfil, root access, etc.)

What Affects Trust

Action	Impact
Normal file edits	No penalty
Running tests	No penalty
Deleting many files	-5 to -15
Installing unknown packages	-5
Network calls to unknown hosts	-10
Accessing /etc/passwd, /etc/shadow	-20
Running `curl	sh`
Modifying system files	-30

Trust scores are stored per-session and aggregated per-sandbox.

Budget Guards

Set a maximum spend per sandbox to prevent runaway costs:

budget: 5.00  # USD — sandbox is killed if this is exceeded

When a sandbox reaches its budget:

1. Warning alert at 80%
2. Critical alert at 95%
3. Sandbox is automatically destroyed at 100%

Snapshots

A snapshot is a point-in-time capture of a sandbox's filesystem, stored as a compressed archive.

• Manual snapshots — create anytime via CLI or dashboard
• Auto-snapshots — created automatically when a sandbox is paused
• Restore — restore a snapshot into any sandbox
• Fork — create a new sandbox from a snapshot
• Download — export as .tar.gz

Limits: 20 snapshots per sandbox, 10 GB total per account.

Preview URLs

When an agent starts a web server inside a sandbox, Caged automatically detects the listening port and generates a public preview URL:

https://cage-a1b2c3d4-3000.preview.caged.dev

• Auto-detected via /proc/net/tcp scanning
• Optional password protection
• Rate-limited (100 req/min)
• HTTPS with wildcard cert

Network Modes

Control what a sandbox can access:

Mode	Description
full	Unrestricted internet access (default)
allowlist	Only specified hosts are reachable
none	No network access at all

network_mode: allowlist
allowed_hosts:
  - api.openai.com
  - registry.npmjs.org

Config-as-Code

A .caged.yaml file in your repo root defines reproducible sandbox settings. See the full guide.

template: node-20
resources:
  cpu: 2
  memory: 1024
  disk: 10
timeout: 1800
budget: 5.00
init_script: npm install
network_mode: allowlist
allowed_hosts:
  - api.openai.com