opencode Integration

opencode is an open-source terminal AI coding agent. The heyvm install-opencode command wires opencode up to the same heyvm capabilities Claude Code already has — sandbox tools, slash commands, and (optionally) sandboxed bash execution.

What you get

MCP tools — heyvm --mcp is registered as an MCP server in opencode.json. opencode discovers ~20 tools for sandbox lifecycle, exec, archives, port forwarding, snapshots, and more. No extra wiring required.
Slash commands — seven /heyvm-* commands (sandbox, system, proxy, deploy, login, firecracker, api) generated from the same source as the Claude Code skills. Plus /heyvm-use to pick the active sandbox.
Bash routing plugin — opt-in plugin that intercepts opencode's bash tool and runs commands inside a heyvm sandbox instead of on the host.

Install

heyvm install-opencode

Defaults to ~/.config/opencode/ (or $XDG_CONFIG_HOME/opencode). Pass --path to install elsewhere.

If you already have a ~/.config/opencode/opencode.json, the installer merges the heyvm wiring into it — your existing keys are preserved. Use --overwrite-config to replace the file instead.

After installing, launch opencode in any project:

opencode

Type / to see the heyvm commands. Ask the agent something like "create a heyvm sandbox named test-1 and list it" to confirm the MCP tools are wired.

What gets installed

~/.config/opencode/
├── opencode.json                # MCP + plugin registration (merged if present)
├── commands/
│   ├── heyvm-deploy.md
│   ├── heyvm-firecracker.md
│   ├── heyvm-login.md
│   ├── heyvm-proxy.md
│   ├── heyvm-sandbox.md
│   ├── heyvm-system.md
│   └── heyvm-use.md
└── plugins/
    └── heyvm-sandbox-bash/      # bash-routing plugin (compiled JS)

Bash routing (opt-in)

By default the plugin is loaded but inert — bash runs on the host. To route bash through a sandbox, the project needs to be mounted into the sandbox so the model can see your code at the expected path.

1. Create a sandbox with the project mounted

heyvm create --name myapp --type shell --mount "$PWD:/workspace"

2. Select the sandbox inside opencode

/heyvm-use myapp

This writes .opencode/heyvm-session.json in the project. Subsequent bash tool calls are rewritten to:

heyvm exec myapp -- bash -lc 'cd /workspace && <original command>'

To stop routing without unloading the plugin:

/heyvm-use none

Setting a per-project default

Skip the slash command by writing .opencode/heyvm.json in the project:

{ "sandbox": "myapp" }

Or export an env var before launching opencode:

export HEYVM_SANDBOX=myapp
opencode

Selection precedence (first match wins): .opencode/heyvm-session.json → .opencode/heyvm.json → $HEYVM_SANDBOX.

What does not get routed

Some commands run on the host so credentials and recursion work correctly. By default:

heyvm — avoid recursion when the agent calls heyvm itself
git push — host SSH keys are not in the sandbox
gh — host GitHub auth is not in the sandbox

Override the skip list with a comma-separated env var:

export HEYVM_BASH_SKIP="heyvm ,git push,gh ,docker push"

Configuration env vars

Variable	Purpose	Default
`HEYVM_SANDBOX`	Fallback sandbox slug if no `.opencode/heyvm*.json` exists	unset
`HEYVM_BASH_WORKDIR`	Working directory inside the sandbox	`/workspace`
`HEYVM_BASH_SKIP`	Comma-separated command prefixes to NOT route	`heyvm ,git push,gh`

How it compares to other integrations

Use case	Tool
Use opencode in your terminal with sandboxed shell + heyvm tools	This guide
Use Claude Code with sandboxed shell + heyvm tools	`heyvm install-skills`
Open a sandbox in Zed or VS Code over SSH	`heyvm zed <sandbox>`
Drive sandboxes from a custom agent over MCP	`heyvm --mcp` directly
Drive sandboxes from a custom agent over HTTP	API Mode

The opencode integration uses the same MCP server as Claude Code (heyvm --mcp) and the same SSH-bridging mechanism as the Zed integration when bash routing is enabled.

Caveats

Mount required for bash routing. The project must be mounted into the sandbox at /workspace (or override with HEYVM_BASH_WORKDIR). Otherwise routed bash runs in the sandbox's default working directory and the model won't see your files.
No streaming. heyvm exec returns once the command completes — long-running commands look unresponsive in opencode until they finish. Use /heyvm-use none and run them on the host if interactivity matters.
Quoting. The plugin shell-escapes commands, but anything that depends on host-only env vars ($PWD, $HOME, host-installed CLIs) will see the sandbox view instead.
Plugin announcement is via stderr. opencode's plugin API does not yet expose a chat-message channel, so the plugin reports its state to stderr at session start (visible in opencode's log pane).

Troubleshooting

Commands don't appear under /. Confirm ~/.config/opencode/commands/ is populated and restart opencode.

MCP tools don't show up. Verify heyvm --mcp runs from your shell, then check opencode's log pane for MCP errors. The MCP server speaks JSON-RPC over stdio:

echo '{"jsonrpc":"2.0","method":"tools/list","id":1}' | heyvm --mcp | head

Bash routing isn't happening. Check that .opencode/heyvm-session.json exists with a non-null sandbox, and that the sandbox is running (heyvm get <slug>). If the sandbox is stopped, heyvm exec fails.

Bash runs on the host even though I picked a sandbox. Confirm opencode.json lists the plugin: cat ~/.config/opencode/opencode.json | jq .plugin. If empty, re-run heyvm install-opencode --overwrite-config.