Use Hermes Agent

Hermes Agent is an open source autonomous agent built by Nous Research . It runs autonomously for long stretches, builds persistent memory, spawns subagents in parallel, and reaches you on Telegram, Discord, Slack, and other platforms while working on a remote VM.

Hermes has two browser drivers, and Lightpanda plugs into both:

Browser Use mode — the default since August 2026. The agent gets a single browser_exec tool that runs Python against a browser over CDP through the Browser Use CLI .
Built-in browser tools (browser_navigate, browser_snapshot, …) — the older driver, which reaches browsers through agent-browser .

Pick the section below that matches your driver. The setting is the same (browser.engine: lightpanda), what differs is what else has to be true for Hermes to honour it.

Prerequisites

Hermes Agent v0.21.0 or later (hermes update, then hermes --version)
Lightpanda installed and on your PATH — check with which lightpanda

If you don’t have Lightpanda yet, follow the installation guide. Hermes and agent-browser also look in ~/.lightpanda/lightpanda and ~/.local/bin/lightpanda.

⚠️

For the built-in tools path, use Lightpanda 0.3.7 until agent-browser ships its launcher fix: nightly builds from 2026-08-27 onward reject the --timeout flag agent-browser still passes at launch, so Lightpanda never starts and every action silently falls back to Chrome. Browser Use mode is not affected.

Option A — Browser Use mode (the Hermes default)

Since Hermes v0.21.0, Browser Use mode honours browser.engine: lightpanda natively: Hermes starts lightpanda serve itself, one process per session, and hands its endpoint to the Browser Use CLI for every browser_exec call.

Either pick Lightpanda in hermes tools → Browser Automation, or set it in ~/.hermes/config.yaml:


browser:
  cloud_provider: local
  engine: lightpanda

cloud_provider: local matters: browser.engine is the lowest-precedence browser setting in Hermes. It is ignored whenever a cloud provider is active — and on a setup that never picked a browser, any BROWSERBASE_API_KEY, BROWSER_USE_API_KEY or Nous subscription browser in ~/.hermes/.env selects one automatically. A browser.cdp_url / /browser connect override takes precedence too. Since v0.21.0, /browser status and hermes doctor tell you when the engine is set but shadowed, and by what.

Lightpanda holds one page per CDP connection: the first new_tab(url) works, a second one fails with TargetAlreadyLoaded. Hermes tells the agent to navigate with goto_url(url) after the first new_tab, and capture_screenshot() is unavailable — Lightpanda has no graphical renderer.

Option B — Built-in browser tools

Switch Hermes off Browser Use mode and select Lightpanda as the local engine:


# ~/.hermes/config.yaml
browser:
  backend: "off"
  cloud_provider: local
  engine: lightpanda

(/browser use off inside Hermes writes backend: "off" for you.)

The same precedence rules as Option A apply (cloud_provider: local, no CDP override), plus one more: Camoufox (CAMOFOX_URL) also wins over browser.engine on this path.

Hermes drives Lightpanda through agent-browser --engine lightpanda over CDP, the same way it drives local Chrome, with automatic Chrome fallback: Lightpanda handles navigate, snapshot, click, type, scroll, back, press and eval; screenshots, browser_vision, PDF generation, file uploads and anything that errors on Lightpanda are retried on Chrome.

⚠️

Before v0.21.0, on Ubuntu 23.10+, in Docker, or as root, Hermes injected Chromium sandbox flags (--no-sandbox) for every engine, and agent-browser rejects them under Lightpanda (Custom Chrome arguments (--args) are not supported with Lightpanda), so every action failed over to Chrome. Setting AGENT_BROWSER_ARGS yourself does not help; run hermes update.

Verify the configuration

Start Hermes and run /browser status.

Option A shows the engine and the binary Hermes will spawn:


Engine: Lightpanda — Browser Use mode: Hermes spawns `lightpanda serve` per session

If it instead reports browser.engine is 'lightpanda' but it is NOT in use: …, the message names what is shadowing it (a cloud provider, a CDP override, …); see the troubleshooting list below.

Option B shows the engine:


🌐 Browser: local Lightpanda (agent-browser --engine lightpanda)
   ⚡ Lightpanda: faster navigation, no screenshot support
   Automatic Chromium fallback for screenshots and failed commands

Then try a prompt that involves browsing:


Visit https://news.ycombinator.com and list the top 5 story titles.

To prove the engine rather than trust the status line, ask the agent for navigator.userAgent: Lightpanda reports Lightpanda/1.0.

Troubleshooting: Hermes uses Chrome even though I set the engine

Check, in this order:

Is Hermes up to date? Browser Use mode only reads browser.engine from v0.21.0; run hermes update. From there, /browser status and hermes doctor say outright when the engine is shadowed.
Is a cloud provider selected? browser.cloud_provider in config.yaml, or a cloud API key / Nous subscription browser on a never-configured setup. Set cloud_provider: local.
Is a CDP override active? browser.cdp_url or a previous /browser connect (undo with /browser disconnect).
Is Camoufox selected? Unset CAMOFOX_URL.
Linux sandbox flags on Hermes older than v0.21.0 (Option B, see the warning above).
Nightly --timeout rejection (Option B, see Prerequisites): run lightpanda serve --timeout 1 by hand; FATAL app : unknown argument means agent-browser cannot launch this build.