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

# Config-as-Code

> Define reproducible sandbox environments with .caged.yaml.

# Config-as-Code

A `.caged.yaml` file in your repository root defines sandbox settings declaratively. When you run `caged up`, the CLI reads this file and creates a sandbox with the specified configuration.

## Full Reference

```yaml theme={null}
# .caged.yaml — Caged sandbox configuration

# Base template (required)
template: python    # Aliases: python, node  |  Full names: python-312, node-22, etc.

# Compute resources
resources:
  cpu: 2           # vCPUs (1-8)
  memory: 1024     # MB (128-8192)
  disk: 10         # GB (1-50)

# Idle timeout before auto-sleep (seconds)
timeout: 1800      # 30 minutes

# Budget guard (USD) — sandbox killed if exceeded
budget: 5.00

# Git repository to clone into /workspace
repo:
  url: https://github.com/user/project
  branch: main                  # Branch to checkout (optional)
  # commit: abc123              # Specific commit SHA (overrides branch)
  # subdirectory: apps/backend  # Monorepo path to extract
  # token_env: GITHUB_TOKEN     # Env var containing PAT (for private repos)

# Shell command to run after creation (install deps, build, etc.)
init_script: npm install && npm run build

# Pre-install packages before your init_script runs
packages:
  - typescript
  - eslint

# AI coding agents to install
agents:
  - claude          # Claude Code (@anthropic-ai/claude-code)
  - aider           # Aider (aider-chat)

# Environment variables
env:
  NODE_ENV: development
  DATABASE_URL: postgres://localhost/mydb

# Secrets (references, not values — resolved from your account)
secrets:
  - OPENAI_API_KEY
  - ANTHROPIC_API_KEY

# Network access control
network_mode: allowlist   # full, none, allowlist
allowed_hosts:
  - api.openai.com
  - api.anthropic.com
  - registry.npmjs.org
  - github.com
```

## Templates

| Template     | Alias    | Base Image   | Pre-installed                       |
| ------------ | -------- | ------------ | ----------------------------------- |
| `node-22`    | `node`   | Ubuntu 24.04 | Node.js 22, npm, yarn, pnpm, git    |
| `node-20`    | —        | Ubuntu 24.04 | Node.js 20, npm, yarn, pnpm, git    |
| `python-312` | `python` | Ubuntu 24.04 | Python 3.12, pip, poetry, venv, git |
| `python-311` | —        | Ubuntu 24.04 | Python 3.11, pip, poetry, venv, git |
| `minimal`    | —        | Ubuntu 24.04 | git, curl, build-essential          |

**Aliases** resolve to the latest stable version. Use full names when you need a specific version.

```yaml theme={null}
# These are equivalent:
template: python      # → python-312
template: python-312  # explicit version
```

## Precedence

When both `.caged.yaml` and CLI flags are provided, CLI flags take precedence:

```bash theme={null}
# Uses .caged.yaml but overrides CPUs and memory
caged up --cpus 4 --memory 2048
```

## Secrets

Secrets are referenced by name in `.caged.yaml` and resolved from your account's secret store:

```yaml theme={null}
secrets:
  - OPENAI_API_KEY   # Set via dashboard or CLI
```

Set secrets via CLI:

```bash theme={null}
caged secrets set OPENAI_API_KEY sk-...
caged secrets list
caged secrets delete OPENAI_API_KEY
```

<Warning>
  Never put actual secret values in `.caged.yaml`. The file should only contain secret **names** that reference your account's secret store.
</Warning>

## Multiple Environments

Use different config files for different environments:

```bash theme={null}
caged up --config .caged.dev.yaml    # Development
caged up --config .caged.ci.yaml     # CI/CD
caged up --config .caged.prod.yaml   # Production-like
```

## Private Repositories

For private repos, provide authentication via token:

### Option 1: Environment Variable (Recommended)

Reference an environment variable containing your token:

```yaml theme={null}
repo:
  url: https://github.com/your-org/private-repo
  token_env: GITHUB_TOKEN   # Reads $GITHUB_TOKEN at runtime
```

Then run:

```bash theme={null}
export GITHUB_TOKEN=ghp_xxxx
caged up
```

### Option 2: CLI Flag

Pass the token directly (useful in CI):

```bash theme={null}
caged up --repo https://github.com/your-org/private-repo --repo-token $GITHUB_TOKEN
```

### Option 3: Secrets Store

Store your token in the Caged secrets store:

```bash theme={null}
caged secrets set GITHUB_TOKEN ghp_xxxx
```

Then reference it in your config:

```yaml theme={null}
repo:
  url: https://github.com/your-org/private-repo
  token_env: GITHUB_TOKEN

secrets:
  - GITHUB_TOKEN
```

<Info>
  Token formats by provider:

  * **GitHub**: Personal access token (`ghp_...`) or fine-grained token
  * **GitLab**: Personal access token or OAuth token
  * **Bitbucket**: App password
</Info>

## Monorepo Support

Extract a subdirectory from a monorepo:

```yaml theme={null}
repo:
  url: https://github.com/your-org/monorepo
  subdirectory: apps/backend   # Only this path is kept in /workspace
```

## Validation

The CLI validates your config before creating a sandbox:

```bash theme={null}
caged validate              # Validates .caged.yaml
caged validate --config ./my-config.yaml
```

Common validation errors:

| Error                     | Fix                                                                     |
| ------------------------- | ----------------------------------------------------------------------- |
| `unknown template`        | Use one of: `node-22`, `node-20`, `python-312`, `python-311`, `minimal` |
| `cpu must be 1-8`         | Reduce CPU count                                                        |
| `memory must be 128-8192` | Adjust memory within range                                              |
| `budget must be positive` | Set a positive dollar amount                                            |
| `unknown network_mode`    | Use `full`, `none`, or `allowlist`                                      |