Plugin system

Plugins extend the desktop agent. One manifest — open-bot.plugin.json — describes everything; GitHub repos hold the code and releases; the marketplace is the searchable index.

Manifest

Schema: packages/plugin-kit/schema/open-bot.plugin.schema.json (seeded into desktops and referenced by ob-plugin new scaffolds; kept in sync with validatePluginManifest).

Key fields:

Config guide (CONFIG.md)

Every plugin project ships a repo-root CONFIG.md — the configuration guide the installing agent reads when it configures the plugin with the user. ob-plugin new scaffolds a template; fill it in whenever the manifest declares configs[] or vault slugs (ob-plugin doctor warns when it is missing or still the placeholder).

What goes in it: what the plugin needs configured, each setting and what to ask the user, each vaultCreate slug and where the user gets the key, the ask → fill → verify order (using ob-plugin settings / ob-plugin vault — never echo secret values), and how to verify the plugin works. It ships with the release tarball, is extracted by the control plane at install, and lands on the desktop as ~/.config/open-bot/plugin-<id>.CONFIG.md; the agent prints it with ob-plugin guide <id>. Lifecycle follows the plugin: overwritten on upgrade, restored on enable and boot re-sync, removed on disable/uninstall. Because it is agent-facing instructions, the marketplace security review reads CONFIG.md on every publish as a prompt-injection surface.

Dashboard pages

A plugin can ship a live dashboard — the Apps tab in the main navigation bar, where the user picks a plugin page and interacts with live data (stock lists, trackers, admin panels).

The proxy strips cookies/auth toward the plugin and injects x-open-bot-page-token; ports come from a dedicated range (4740-4719-style, per-plugin deterministic). Upgrades and settings changes restart the server so it observes new config; disable/uninstall stop it.

Install surfaces

• Tools land in /usr/local/bin/ob-plugin-<id>-*; apply-plugin-auth.sh writes the vault config.
• The config guide ships to ~/.config/open-bot/plugin-<id>.CONFIG.md when the plugin has a CONFIG.md.
• The install log on the installed_plugins row reverses everything on uninstall.
• Disable is deep: pauses cron, unloads OpenViking skills, drops vault config + opencode surfaces; enable restores from the stored manifest snapshot.
• Failed root setup shows “setup failed — retry” on the Config page's Plugins tab (POST /api/plugins/installed/:id/setup).

Vault

permissions.vaultCreate declares key slugs the plugin owns (created empty at install); permissions.vaultRead consumes shared user keys. The config file's vault branch is generated from the key vault, so treat it as read-only — local edits are overwritten on enable/reinstall/settings changes. The durable write path is POST /api/plugins/installed/:id/vault (agent token, write-only — values are never returned) for slugs in that plugin's vaultCreate, or from the desktop: ob-plugin vault ID SLUG=value. The user can also fill any slug on the Config Keys page.

Persistence across desktop recreates

A desktop update (or any sleep/start cycle that recreates the container) wipes the container filesystem except the /home and /usr/local volumes. What survives without any re-run:

• plugin tools and payload files (/usr/local/bin/ob-plugin-<id>-*)
• vault config (~/.config/open-bot/plugin-<id>.json), agentsMd files, patched opencode.json surfaces, and anything else under /home/agent

What does not survive: anything a setup command installed into the container layer (apt packages, /venv, etc.). The boot re-apply re-runs setup.commands right after the container starts — it is what restores them, so keep the commands idempotent and expect a freshly recreated desktop to need a few minutes before root-installed dependencies are back.

Updates

• installed_plugins.latest_version refreshes from the marketplace (throttled, on GET /api/plugins/installed).
• ob-plugin outdated / update; dashboard “update to v…” button.
• app_settings.plugin_auto_update: off (default) or stable (auto-installs newer approved stables).
• Install policy app_settings.plugin_install_policy: manual (default, confirm dialog) or auto (also installs pending-review plugins).

Local development

ob-plugin install --path <plugin-root>

No publish needed; Re-install re-reads the path; Remove uninstalls. Schema changes need bun run db:generate and an image rebuild for existing desktops.