Build a Hermes Browser Provider Plugin

Implement a cloud-browser provider that owns remote session lifecycle while Hermes keeps the common browser tool surface. This guide focuses on the public implementation contract; the official Hermes documentation remains the source of truth as interfaces evolve.

How the interface works

A browser provider does not reimplement navigation, clicking, or screenshots. It creates a remote browser session, returns a CDP websocket URL, and tears the session down.

The active backend is selected with browser.cloud_provider. Registration uses ctx.register_browser_provider(...), allowing the common browser_* dispatcher to stay provider-neutral.

The provider contract includes stable identity, a cheap is_available() check, create_session(), close_session(), and best-effort emergency_cleanup(). Availability checks must not perform network calls because setup screens may call them frequently.

Session metadata must include the agent-browser session name, provider session identifier, CDP URL, and feature flags. Setup metadata should make the backend selectable through hermes tools.

Practical checklist

Start from the closest bundled browser provider rather than a blank abstraction.
Keep API keys in environment-backed setup fields.
Return all required session metadata and use unique task-scoped session names.
Make normal and emergency cleanup idempotent and non-throwing.
Test create, connect, use, close, and interrupted-process cleanup.

Common pitfalls

Putting provider-specific branches into the shared browser dispatcher.
Making network calls from is_available().
Returning a dashboard URL instead of a CDP websocket URL.
Treating cleanup as optional and leaking paid remote sessions.

Verification steps

Select the provider in hermes tools and confirm browser.cloud_provider.
Create a session and run a small navigate/snapshot flow.
Verify the provider session closes after normal completion.
Interrupt a test run and confirm emergency cleanup does not raise or leave a session running.

Official reference

https://hermes-agent.nousresearch.com/docs/developer-guide/browser-provider-plugin