Build a Hermes Dashboard Plugin with Scoped Routes

A Hermes dashboard plugin can add a tab, place a component into a shell slot, augment a built-in page, or deliberately replace a page. It can also expose backend API routes through the plugin boundary. The safest plugin is small, namespaced, reversible, and explicit about what data and operations it owns.

Choose the smallest extension point

Do not replace a built-in page when a slot or augmentation is enough. A normal tab is appropriate for a distinct workflow. A hidden tab can provide slot-only UI. Page-scoped slots can add context near a built-in surface without taking ownership of the whole page. Overrides create the largest compatibility burden and should be rare.

Package checklist

Create a dedicated plugin directory and unique manifest identifier.
Declare the smallest tab or slot surface that satisfies the workflow.
Use a documented icon and human-readable label.
Load frontend code through the dashboard plugin SDK.
Namespace CSS beneath the plugin root.
Put backend handlers in the plugin’s documented dashboard API module.
Authenticate and authorize every sensitive backend operation.
Return stable JSON errors rather than raw exceptions or secrets.
Support plugin rediscovery/reload without a full reinstall.
Keep uninstall and rollback steps in the plugin README.

Frontend and backend boundary

Use the SDK to register UI surfaces and call plugin-owned backend routes. Do not reach into undocumented dashboard globals or scrape internal DOM state. For built-in Hermes endpoints, use the SDK’s documented request path and preserve the dashboard’s normal authentication boundary.

A backend route inherits neither good authorization nor safe validation automatically. Validate method, content type, request size, and fields. Keep filesystem access and external calls narrow. Never return environment values, provider tokens, private paths, stack traces, or unrelated records to the browser.

Lifecycle and reload

Plugin discovery can be refreshed without restarting the entire installation. Design registration to tolerate reload and hot-module replacement: duplicate registration should not create duplicate tabs, listeners, timers, or network requests. A clean teardown path is especially important for shell widgets that subscribe to live state.

Common pitfalls

Replacing a built-in page to add one small card.
Using a manifest ID that collides with another plugin.
Registering global CSS that changes unrelated dashboard pages.
Calling private internals instead of the supported SDK.
Exposing an unauthenticated convenience route on the dashboard backend.
Returning raw provider or filesystem errors to the client.
Creating duplicate event listeners after each reload.
Treating a visible tab as proof that its backend route is authorized.

Verification steps

Force plugin discovery and confirm exactly one plugin registration appears.
Open every declared tab and slot at desktop and phone widths.
Reload the plugin repeatedly and confirm no duplicate tabs, timers, requests, or console errors.
Exercise backend routes with valid, invalid, oversized, and unauthorized requests.
Verify JSON responses contain no secrets, private paths, or raw stack traces.
Disable or remove the plugin and confirm built-in dashboard pages return to normal.
Restart Hermes and repeat one frontend and one backend smoke test.

Official documentation

https://hermes-agent.nousresearch.com/docs/user-guide/features/extending-the-dashboard