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, 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 opencode2 / pi / claude-code, use ~/.config/agents-sandbox/opencode2/ / .../pi/ / .../claude/. 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.

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