opencode-plugin-dashboard

A web-based dashboard for managing OpenCode plugins — view, toggle, add, and remove plugins, validate that they load, and hot-reload your config, all from a single local page.

It ships as an npm package run via npx opencode-plugin-dashboard.

How it's built: a tiny local HTTP server (binds to 127.0.0.1 only) reads and writes your opencode.json, proxies to OpenCode's own /config/reload endpoint to apply changes live, and runs best-effort plugin health checks. The frontend talks to that bridge over fetch — no browser file-system APIs, no manual drag-and-drop required for the common case.

Requirements

• Node.js 18+ or Bun 1.0+ (Node is fine)
• OpenCode installed (for live reload via /config/reload)

Usage

npx opencode-plugin-dashboard

Or on Windows, no terminal needed: double-click start.bat in this folder — it checks for Node.js, runs the app, and opens the browser for you. Close the window to stop.

The server auto-detects your OpenCode config in this order:

1. The nearest project config, walking up from the current directory to the filesystem root — so launching the dashboard from a subdirectory (e.g. myproject/tools/dashboard) still finds myproject/opencode.json or myproject/.opencode/opencode.json at each level.
2. ~/.config/opencode/opencode.json / ~/.config/opencode/opencode.jsonc

It picks a free port (starting at 4096), prints a startup banner, and opens your default browser to the dashboard.

CLI options

opencode-plugin-dashboard [--port <n>] [--config <path>] [--oc-url <url>] [--oc-port <n>]

  --port <n>        Local dashboard port (default 4096; auto-picks a free port if taken)
  --config <path>   Explicit path to the OpenCode config to manage
  --oc-url <url>    URL of a running OpenCode server (e.g. http://127.0.0.1:4096) for /api/reload
  --oc-port <n>     Port of the running OpenCode server (implies 127.0.0.1)
  --host <h>        Host of the running OpenCode server (default 127.0.0.1)

Features

Plugin management

• See every configured plugin with its enabled/disabled state at a glance.
• Toggle a plugin on/off, add one by npm name, or remove one.
• Every mutation follows one shared optimistic update → save → reload → confirm flow, so you always know whether it took effect in your real running OpenCode instance.

Live reload

After a config save, the dashboard automatically calls POST /config/reload on your running OpenCode server. That hot-reloads opencode.json / .opencode/, reinstantiates plugins, and restarts MCP servers (queuing the reload if a session is active). If OpenCode isn't reachable — or its server is on a non-default port — the dashboard shows a clear warning instead of failing silently.

Discovering OpenCode's server (best-effort, in priority order):

1. OPENCODE_PLUGIN_DASHBOARD_OC_URL env var, or --oc-url.
2. server.port / server.hostname from your OpenCode config.
3. A probe of 127.0.0.1:4096 (the opencode serve default).

Note: the OpenCode TUI assigns a random port unless you set server.port in your config. If the dashboard can't reach OpenCode, either set server.port in opencode.json (and use opencode serve/opencode web), or pass --oc-url.

Plugin validation

Every plugin row has a Validate button that runs a best-effort health check: it tries to resolve/import the package and inspect its export shape, then reports PASS / WARNING / FAIL (categorized as ok / warning / error).

Every time the dashboard opens, it automatically validates every configured plugin (non-blocking, independent requests per plugin) so you can instantly see which are healthy, which are warnings, and which are failing to load.

⚠️ This is inherently best-effort: OpenCode has no formal plugin health-check API, so the result is an indication, not a guarantee.

Load Plugins (auto-install)

The Load Plugins button (and an automatic run on every page open) installs any configured plugin that isn't present in the config directory's node_modules. It shells out to npm install <names> --ignore-scripts --no-save (so a hung postinstall like oh-my-openagent's interactive TUI never blocks), then reports what was installed vs. still missing. Each missing package is installed so OpenCode can actually load it.

Locate OpenCode

The Locate OpenCode button resolves where the OpenCode application lives on this machine — the opencode binary on PATH (via where/which) or common install locations (npm global bin, the OpenCode installer dirs) — and shows the resolved path in the status log. It also reports the server URL OpenCode would run on for hot-reload.

Theming

Two deliberately-separate layers:

1. Dashboard UI (local, instant) — pick a dark preset and the dashboard restyles immediately via CSS custom properties. Never touches OpenCode.
2. OpenCode theme — write a theme name to your config directory's tui.json (OpenCode keeps its UI theme in tui.json, not opencode.json), then hot-reloads through the same save → reload flow.

API (the local bridge)

| Method | Path | Description | | --- | --- | --- | | GET | /api/config | Read current config (JSONC-safe) | | POST | /api/config | Write config back (keeps a .bak) | | POST | /api/reload | Proxy to OpenCode's /config/reload | | POST | /api/plugins/:name/validate | Best-effort plugin health check | | POST | /api/plugins/load | Install missing configured plugins (npm install --ignore-scripts) | | GET | /api/system/opencode | Locate the OpenCode application path + server URL | | GET | /api/theme | Read current tui.json theme | | POST | /api/theme | Write theme to tui.json |

Security

• The server binds to 127.0.0.1 only — never 0.0.0.0. It writes files and spawns processes, so it must never be reachable from the network.
• All file paths it touches are validated to resolve inside the detected config directory (path-traversal guard).
• Responsive header headers (X-Content-Type-Options, Referrer-Policy, no-store) are set on responses.

Development

npm link   # so `opencode-plugin-dashboard` resolves locally
opencode-plugin-dashboard

License

MIT — see LICENSE.