---
title: Config-as-Code
description: "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
# .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
# 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
# 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
secrets:
  - OPENAI_API_KEY   # Set via dashboard or CLI
```

Set secrets via CLI:

```bash
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
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
repo:
  url: https://github.com/your-org/private-repo
  token_env: GITHUB_TOKEN   # Reads $GITHUB_TOKEN at runtime
```

Then run:

```bash
export GITHUB_TOKEN=ghp_xxxx
caged up
```

### Option 2: CLI Flag

Pass the token directly (useful in CI):

```bash
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
caged secrets set GITHUB_TOKEN ghp_xxxx
```

Then reference it in your config:

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