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

Warning alert at 80%
Critical alert at 95%
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

Getting Started

Guides

Core Concepts

Core Concepts

Sandboxes

Sandbox Lifecycle

Idle Timeout

Sessions

Trust Scores

What Affects Trust

Budget Guards

Snapshots

Preview URLs

Network Modes

Config-as-Code

​Core Concepts

​Sandboxes

​Sandbox Lifecycle

​Idle Timeout

​Sessions

​Trust Scores

​What Affects Trust

​Budget Guards

​Snapshots

​Preview URLs

​Network Modes

​Config-as-Code

Core Concepts

Sandboxes

Sandbox Lifecycle

Idle Timeout

Sessions

Trust Scores

What Affects Trust

Budget Guards

Snapshots

Preview URLs

Network Modes

Config-as-Code