---
title: Core Concepts
description: "Key concepts in the Caged platform: sandboxes, sessions, trust scores, and more."
sidebarTitle: "Core Concepts"
---

# Core Concepts

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

<Info>
New to Caged? Start with the [Quickstart](/quickstart) to create your first sandbox, then come back here to understand the concepts in depth.
</Info>

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

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

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

```yaml
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](/guides/config-as-code).

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