Manage config in the sandbox

Own the sandbox’s configuration declaratively: self-contained, reproducible, and able to keep raw secret values out of the VM. This extends Switch from your existing agent.

Note: If you are new to coding agents, set up your agent (opencode, opencode2, pi, claude-code, codex, hermes, or oh-my-pi) 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 opencode2 / pi / claude-code / codex / hermes / oh-my-pi, use ~/.config/agents-sandbox/opencode2/ / .../pi/ / .../claude/ / .../codex/ / .../hermes/ / .../oh-my-pi/. An opencode2 dir is separate from the opencode one; see the fallback note in Agent configuration.) 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.

For keys that are specific to one project rather than every project, put them in the per-slug secrets file ~/.config/agents-sandbox/<slug>/env.secret.yaml (slug = the project’s repo slug, so every clone of one remote shares the file). It merges after the generic user file and before the project’s, and keeps the keys off the committed project config.

4. Provision files and hooks

Map dotfiles and startup hooks into the VM home — see Home provisioning & startup hooks.

Next steps

Docs built from release v0.7.0