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:

Option 1: Environment Variable (Recommended)

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`

Getting Started

Guides

Config-as-Code

Config-as-Code

Full Reference

Templates

Precedence

Secrets

Multiple Environments

Private Repositories

Option 1: Environment Variable (Recommended)

Option 2: CLI Flag

Option 3: Secrets Store

Monorepo Support

Validation

​Config-as-Code

​Full Reference

​Templates

​Precedence

​Secrets

​Multiple Environments

​Private Repositories

​Option 1: Environment Variable (Recommended)

​Option 2: CLI Flag

​Option 3: Secrets Store

​Monorepo Support

​Validation

Config-as-Code

Full Reference

Templates

Precedence

Secrets

Multiple Environments

Private Repositories

Option 1: Environment Variable (Recommended)

Option 2: CLI Flag

Option 3: Secrets Store

Monorepo Support

Validation