Skip to main content

​
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: node-20   # node-20, python-312, go-122, minimal

# 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 the sandbox
repo: https://github.com/user/project

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

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

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

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

​
Templates

TemplateBase ImagePre-installed
node-20Ubuntu 22.04Node.js 20, npm, yarn, pnpm, git
python-312Ubuntu 22.04Python 3.12, pip, venv, git
go-122Ubuntu 22.04Go 1.22, git
minimalAlpine 3.19git, curl, vim

​
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

​
Validation

The CLI validates your config before creating a sandbox: 
caged validate              # Validates .caged.yaml
caged validate --config ./my-config.yaml
Common validation errors:
ErrorFix
unknown templateUse one of: node-20, python-312, go-122, minimal
cpu must be 1-8Reduce CPU count
memory must be 128-8192Adjust memory within range
budget must be positiveSet a positive dollar amount
unknown network_modeUse full, none, or allowlist