Skip to main content

​
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
StateDescriptionBilling
pendingVM is bootingNo charge
runningAgent is activeBilled per-second
pausedFrozen in memory (sleep)No charge
destroyedPermanently removedNo 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:
ScoreRatingMeaning
90–100ExcellentStandard development, no risky actions
70–89GoodMinor concerns (large file deletes, etc.)
50–69CautionSuspicious patterns detected
0–49AlertDangerous behavior (network exfil, root access, etc.)

​
What Affects Trust

ActionImpact
Normal file editsNo penalty
Running testsNo penalty
Deleting many files-5 to -15
Installing unknown packages-5
Network calls to unknown hosts-10
Accessing /etc/passwd, /etc/shadow-20
Running `curlsh`-25
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:
ModeDescription
fullUnrestricted internet access (default)
allowlistOnly specified hosts are reachable
noneNo 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