Skip to content
LUNAROUTEDocs

OpenCode

opencode is configured through one plugin entry. @lunaroute/opencode-extension registers LunaRoute as a provider, logs you in with /connect, and syncs models from /v1/models — so the config file you end up with says nothing about the gateway except that the plugin exists.

1. Add the extension

Section titled “1. Add the extension”
Terminal window
npx @lunaroute/cli setup opencode

It merges one key into ~/.config/opencode/opencode.json (JSONC, everything else you have in there preserved):

{
  "$schema": "https://opencode.ai/config.json",
  "plugin": ["@lunaroute/opencode-extension"]
}

Restart opencode (or start it) — npm plugins install themselves at startup. If you run a non-default gateway, setup also pins provider.lunaroute.options.baseURL to your routing URL so the extension talks to the right host.

Two other outcomes, both from the same command:

  • --key skips the browser: npx @lunaroute/cli setup opencode --key lr_… --yes verifies the key, installs the extension and stores it in ~/.local/share/opencode/auth.json, so opencode starts signed in.
  • Decline the extension and setup merges a static provider block instead — npm: "@ai-sdk/openai-compatible", options.baseURL at https://gw.lunaroute.com/v1, apiKey: {env:LUNAROUTE_API_KEY} — plus an export LUNAROUTE_API_KEY=… line to paste into your shell profile. That path has no login and no model sync: the model list is whatever the catalog held at setup time.

2. Log in and pick a model

Section titled “2. Log in and pick a model”

Inside opencode:

/connect      # browser login, if setup carried no key
/models       # pick a lunaroute/* model

Models auto-sync from /v1/models, so the picker follows your organization’s catalog rather than a list frozen at setup time.

3. Undo

Section titled “3. Undo”

Remove "@lunaroute/opencode-extension" from the plugin array in ~/.config/opencode/opencode.json and restart. To sign out as well, delete the lunaroute entry from ~/.local/share/opencode/auth.json ($XDG_DATA_HOME moves that directory). A static provider.lunaroute block from the declined-extension path, and the matching export LUNAROUTE_API_KEY=…, are yours to delete from opencode.json and your shell profile.

There is no one-session lunaroute run opencode; run covers Claude Code, Codex and Zed.

Verify without starting opencode

Section titled “Verify without starting opencode”
Terminal window
curl https://gw.lunaroute.com/v1/models \
  -H "Authorization: Bearer $LUNAROUTE_API_KEY"
Section titled “Related”
  • CLI — install, run, setup, and the Windows/WSL notes.
  • Harness setup — the other harnesses, and the MCP server.
  • Pi — the other extension-first harness.
LunaRoute documentation