> ## 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.

# Quickstart

> Create your first Caged sandbox in under 2 minutes.

# Quickstart

Get an AI agent running in an isolated sandbox in 3 steps.

<Steps>
  <Step title="Install the CLI">
    <CodeGroup>
      ```bash macOS (Homebrew) theme={null}
      brew tap caged-dev/tap
      brew install caged
      ```

      ```bash Linux theme={null}
      curl -fsSL https://get.caged.dev | sh
      ```

      ```bash Go theme={null}
      go install github.com/caged-dev/cli/cmd/caged@latest
      ```
    </CodeGroup>

    Verify the installation:

    ```bash theme={null}
    caged version
    # caged v0.1.0 (linux/amd64)
    ```
  </Step>

  <Step title="Authenticate">
    Sign up at [caged.dev](https://caged.dev/signup), then log in:

    ```bash theme={null}
    caged login
    # Enter your API URL and API key
    ```

    <Tip>
      Alternatively, set the `CAGED_API_KEY` environment variable — useful in CI/CD.

      ```bash theme={null}
      export CAGED_API_KEY=caged_...
      ```
    </Tip>
  </Step>

  <Step title="Create a Sandbox">
    **Option A: Quick start with flags**

    ```bash theme={null}
    caged sandboxes create --template node --cpus 2 --memory 1024
    ```

    **Option B: Config-as-code (recommended for teams)**

    Create a `.caged.yaml` in your project root:

    ```yaml .caged.yaml theme={null}
    template: node    # Alias for node-22 (or use python, minimal, etc.)
    resources:
      cpu: 2
      memory: 1024
      disk: 10
    timeout: 1800
    budget: 5.00
    init_script: npm install
    env:
      NODE_ENV: development
    ```

    Then just run:

    ```bash theme={null}
    caged up
    ```

    The CLI reads `.caged.yaml` automatically — no flags needed.
  </Step>
</Steps>

## What Happens Next

<Info>
  Sandboxes boot in \~300ms using Firecracker microVMs. Each gets its own Linux kernel — full OS-level isolation.
</Info>

1. A Firecracker microVM boots with your chosen template
2. Your repo is cloned into `/workspace`
3. The `init_script` runs (e.g., `npm install`)
4. The sandbox is ready for your agent

```bash theme={null}
# Output from `caged up`:
✓ Sandbox created: cage-a1b2c3d4
  Status:   running
  Template: node-20
  IP:       10.0.1.42
  Budget:   $5.00

→ Connect: caged connect cage-a1b2c3d4
→ Dashboard: https://caged.dev/sandboxes/cage-a1b2c3d4
```

## Connect to Your Sandbox

```bash theme={null}
# Interactive terminal
caged connect cage-a1b2c3d4

# Or run a single command
caged exec cage-a1b2c3d4 -- npm test
```

## Monitor in the Dashboard

Open [caged.dev/dashboard](https://caged.dev/dashboard) to see:

* **Live terminal** — watch what the agent is doing
* **File browser** — see files as they change
* **Cost tracker** — real-time spend in dollars
* **Trust score** — behavioral safety rating
* **Preview URLs** — click to see web apps the agent builds

## Clean Up

```bash theme={null}
# Pause (stop billing, keep state)
caged sleep cage-a1b2c3d4

# Resume later
caged wake cage-a1b2c3d4

# Destroy permanently
caged destroy cage-a1b2c3d4
```

## Next Steps

<CardGroup cols={2}>
  <Card title="Concepts" icon="book" href="/concepts">
    Understand sandboxes, sessions, and trust scores
  </Card>

  <Card title="Config-as-Code" icon="file-code" href="/guides/config-as-code">
    Full .caged.yaml reference
  </Card>

  <Card title="Agent Setup" icon="robot" href="/guides/agents">
    Connect Claude Code, Cursor, and other agents
  </Card>

  <Card title="CLI Reference" icon="terminal" href="/cli/commands">
    All CLI commands
  </Card>
</CardGroup>