> ## Documentation Index
> Fetch the complete documentation index at: https://docs.caged.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Core Concepts

> Key concepts in the Caged platform: sandboxes, sessions, trust scores, and more.

# 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 theme={null}
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 theme={null}
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 theme={null}
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 theme={null}
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
```