Manage config in the sandbox

Own the sandbox’s configuration declaratively: Self-contained, reproducible, and with secrets that are never written into the VM. Extends on Switch from your existing agent.

New to coding agents? Set up your agent (opencode, pi, or claude-code) on your host first, then come back here.

1. Turn off host-config fallback 

# ~/.config/agents-sandbox/config.yaml
provision-host-config: false

2. Bring over your config

Copy your existing agent config into the sandbox snippet directory and adapt it:

mkdir -p ~/.config/agents-sandbox/opencode
for f in "$HOME"/.config/opencode/* "$HOME"/.config/opencode/.[!.]*; do
  case "$(basename "$f")" in
    node_modules|package.json|bun.lock) continue ;;
  esac
  cp -R "$f" ~/.config/agents-sandbox/opencode
done

(For pi / claude-code, use ~/.config/agents-sandbox/pi/ / .../claude/.) Snippets matching the agent’s pattern (e.g. opencode*.json*) are deep-merged into the VM config; see Agent configuration.

3. Add secrets

Deliver API keys / tokens so they never touch the VM disk — see Secrets:

# ~/.config/agents-sandbox/env.secret.yaml
ANTHROPIC_API_KEY:
  value: sk-ant-xxxxxxxx
  host: provider.example

Then reference it in your config with {env:ANTHROPIC_API_KEY} (opencode) instead of the literal key.

4. Provision files & hooks

Map dotfiles and startup hooks into the VM home — see

Next steps

Docs built from release main