Guides
View as Markdown Open in ChatGPT Open in Claude

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

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

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

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

secrets:
  - OPENAI_API_KEY   # Set via dashboard or CLI

Set secrets via CLI:

caged secrets set OPENAI_API_KEY sk-...
caged secrets list
caged secrets delete OPENAI_API_KEY

Never put actual secret values in .caged.yaml. The file should only contain secret names that reference your account's secret store.

Multiple Environments

Use different config files for different environments:

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:

Reference an environment variable containing your token:

repo:
  url: https://github.com/your-org/private-repo
  token_env: GITHUB_TOKEN   # Reads $GITHUB_TOKEN at runtime

Then run:

export GITHUB_TOKEN=ghp_xxxx
caged up

Option 2: CLI Flag

Pass the token directly (useful in CI):

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:

caged secrets set GITHUB_TOKEN ghp_xxxx

Then reference it in your config:

repo:
  url: https://github.com/your-org/private-repo
  token_env: GITHUB_TOKEN

secrets:
  - GITHUB_TOKEN

Token formats by provider:

  • GitHub: Personal access token (ghp_...) or fine-grained token
  • GitLab: Personal access token or OAuth token
  • Bitbucket: App password

Monorepo Support

Extract a subdirectory from a monorepo:

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:

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
Was this page helpful?