Skip to main content

Install on an unmanaged browser

The governed way to deploy the browser extension is force-install: the agent one-liner on Windows and Linux, or your MDM/GPO, pushes it so an ordinary user cannot remove or disable it. That is the enforced control, and it is documented on Deploy on managed browsers.

This page is the other case: a browser no policy reaches — a personal Mac, a Mac without an MDM configuration profile, or a workstation where you are evaluating or developing Lumen. You install the extension yourself, from its Chrome Web Store listing, and make sure the local agent's native-messaging host is registered for it.

This is an evaluation path, not the enforced control

An extension you install yourself is user-removable — the person at the keyboard can turn it off or delete it. Treat enforcement here as evaluation only; it is not the tamper-resistant control that force-install gives you. When you need the governed deployment, use managed force-install. On a fleet you cannot reach at all, the gateway and cloud collectors see the traffic regardless of the browser.

Before you start​

The agent must be installed and running. The extension has no detection or transport of its own — it reaches the local agent over Native Messaging for every verdict. Install it first (Install the agent) and confirm with lumen-agent status. The one-liner also registers the native-messaging host for every user of the machine, for both published builds of the extension, so on a machine it installed, step 2 below is already done. On Windows that registration is automatic now (HKLM registry keys); there is no reg add to run.

An endpoint installed by v2.9.0 or earlier and upgraded since by the agent itself (automatically or from the console) does not have this registration yet: a self-upgrade replaces the binary and nothing else. Re-run the one-liner on it.

1. Install the extension​

Open the Lumen Browser Collector on the Chrome Web Store and add it to the browser. Its extension ID is pnbjfklmbahlondakkdjaffkmimofmni on every machine, which is the ID the agent registers its host for.

Click Add to Chrome on the listing, then Add extension.

Or load a build unpacked​

For a development build, or a machine that cannot reach the Chrome Web Store, load the extension from a folder instead. Every release also publishes the packaged extension at https://dl.lumen.wazuh.com/crx/lumen-collector.crx. Unpack it into a folder that will stay where it is, because the browser loads the extension from that folder every time it starts:

mkdir -p ~/lumen-extension && cd ~/lumen-extension
curl -fsSLO https://dl.lumen.wazuh.com/crx/lumen-collector.crx
unzip -o lumen-collector.crx -d dist

A .crx is a zip archive behind a short signature header, so unzip prints a warning about extra bytes at the beginning and then extracts it; that warning is expected. On Windows, 7-Zip opens a .crx the same way. A development build from source is cd extension && npm run build, which produces extension/dist.

Then open chrome://extensions (edge://extensions on Edge), turn on Developer mode, click Load unpacked and select the folder. Note the ID on the extension's card: a copy loaded unpacked can get an ID of its own, and if it is not pnbjfklmbahlondakkdjaffkmimofmni, step 2 needs it.

2. Wire it to the agent​

The extension reaches the agent through the native-messaging host, which must be registered for the extension's ID. The agent one-liner already did this machine-wide. Do it yourself when the agent came from a package (the macOS .pkg, a deb or rpm), or when your unpacked copy has an ID of its own:

lumen-agent browser dev-install                     # the Chrome Web Store build
lumen-agent browser dev-install --id <EXTENSION_ID>  # a copy with its own ID

browser dev-install registers the host for you (per-user). It:

  • writes the Native-Messaging host manifest for every Chromium browser it knows (Chrome, Chromium, Edge), for that ID and for both published builds' IDs;
  • defaults --id to the Chrome Web Store build's ID;
  • defaults --config to the installed agent config (/etc/lumen/agent.yaml when present), so the extension uses the same policy as the rest of the machine;
  • on Windows, also writes the HKCU\Software\<vendor>\NativeMessagingHosts\com.wazuh.lumen registry key that points each browser at the manifest.

Useful flags:

FlagPurpose
--dry-runprint what would be written and exit
--browsers chrome,edgeregister for a subset instead of all
--firefox-id <id>register the Firefox host for a Firefox add-on ID
--config <path>use a specific agent config the host shim passes through

lumen-agent nm uninstall removes your per-user registration again (add --system, as root or from an elevated prompt, for the machine-wide one).

The agent installer leaves a registration like this alone when it names an ID of its own: re-running the one-liner removes only a per-user registration that allows nothing but the published builds (what an earlier installer wrote), and prints what it removed and what it kept. A dev-install with no --id allows exactly the published builds, so a re-run removes it, which loses nothing: the machine-wide registration accepts the same IDs.

3. Verify​

Make sure the agent is running (lumen-agent status), then open a covered AI site — chatgpt.com, claude.ai, perplexity.ai or gemini.google.com — and send a prompt. The interaction is recorded with collector.type: "browser". Watch it locally with lumen-agent's findings, and on a connected endpoint it appears in the console under Interactions. If your policy blocks the prompt, the send is cancelled before it leaves and an in-page notice explains why.

To inspect the bridge itself, open the extension's service worker console from the extensions page — it logs the hello and inspect round-trips with the agent, including the agent's version and the extension's own. A released build reports its release (2.8.0 for v2.8.0); a build you made yourself reports the extension's package.json version (0.1.0) unless you name the release you checked out: LUMEN_EXTENSION_VERSION=v2.8.0 npm run build.

The Chrome Web Store build reports the version the store last approved, which can lag the release, because a store upload goes live only once Google's review passes: on 2026-09-28 the listing served 0.1.0 while release v2.8.0's self-hosted package was 2.8.0, and it served 2.8.0 by 2026-09-30.

Where the host manifest lands​

The host name is always com.wazuh.lumen. The agent installer registers it machine-wide:

BrowsermacOSLinuxWindows
Chrome/Library/Google/Chrome/NativeMessagingHosts//etc/opt/chrome/native-messaging-hosts/HKLM key ¹
Chromium/Library/Application Support/Chromium/NativeMessagingHosts//etc/chromium/native-messaging-hosts/HKLM key ¹
Edge/Library/Microsoft/Edge/NativeMessagingHosts//etc/opt/edge/native-messaging-hosts/HKLM key ¹

dev-install registers it per-user:

BrowsermacOSLinuxWindows
Chrome~/Library/Application Support/Google/Chrome/NativeMessagingHosts/~/.config/google-chrome/NativeMessagingHosts/HKCU key ²
Chromium~/Library/Application Support/Chromium/NativeMessagingHosts/~/.config/chromium/NativeMessagingHosts/HKCU key ²
Edge~/Library/Application Support/Microsoft Edge/NativeMessagingHosts/~/.config/microsoft-edge/NativeMessagingHosts/HKCU key ²
Firefox~/Library/Application Support/Mozilla/NativeMessagingHosts/~/.mozilla/native-messaging-hosts/HKCU key ²

¹ HKLM\Software\Google\Chrome\NativeMessagingHosts\com.wazuh.lumen (and Chromium, Microsoft\Edge), whose default value is %ProgramFiles%\Lumen\nm\com.wazuh.lumen.json, beside the agent, where only an administrator can change it. The shim it launches sits beside it.

² The same keys under HKCU, whose default value is %AppData%\Lumen\NativeMessagingHosts\com.wazuh.lumen.json.

A browser reads the per-user registration before the machine-wide one, so a per-user one shadows the installer's. That is why dev-install always includes both published builds' IDs.

Browser support today​

BrowserUnmanaged (this page)Notes
Chrome 120 or newerYesPrimary target
Edge 120 or newerYesPrimary target; installs from the Chrome Web Store once other stores are allowed
ChromiumYesSame engine and build as Chrome
BraveNot yetNo native-messaging host is registered for Brave, so the extension cannot reach the agent
FirefoxLater trackBuild not shipped yet; load path above is for when it lands
SafariNoIts extensions ship inside a notarized app via the App Store; not reachable this way
Any snap or flatpak browser (Linux)NoA confined browser cannot launch the agent's native-messaging host. Ubuntu ships Chromium and Firefox as snaps; use Google Chrome from its .deb or .rpm instead

On Linux, install.sh names each browser it cannot reach in a NOT COVERED: line after the browser step: every Chromium, Brave or Firefox snap and every Chrome, Chromium, Brave, Edge or Firefox flatpak it finds, Brave from its .deb or .rpm (which reads the force-install policy, but is not supported yet), and Firefox from a package while there is no Lumen Firefox build. Nothing is written into a snap's or flatpak's own paths.

Troubleshooting​

  • The host never answers. The agent may not be running (lumen-agent status), or the host may be registered for a different ID than the one the browser shows. Re-run lumen-agent browser dev-install --id <the ID on chrome://extensions>. A per-user registration from an earlier release can also shadow the machine-wide one: lumen-agent nm uninstall (as that user) removes it. On Windows, delete a HKCU\Software\Google\Chrome\NativeMessagingHosts\com.wazuh.lumen key you added by hand for v2.9.0 or earlier, unless the installer already did (it does when it runs as the account that added it).
  • The extension is not in Edge on a Windows machine the installer armed. On a machine not joined to an Active Directory domain, Edge force-installs only from Microsoft Edge Add-ons, so the installer's Chrome Web Store entry arms Chrome there and not Edge. Add it to Edge by hand from the listing (step 1).
  • Nothing is captured on a site. Capture is allowlist-only — it runs only on the covered AI-provider domains, by design (Browser extension).
  • A covered site sends prompts but none are recorded. Open that page's DevTools console, include the Verbose level, and send a prompt. A line like [lumen] anthropic-claude: prompt request not inspected (unsupported_encoding: br); sent unaltered means the extension saw the prompt request but could not read its body (here, a compression it cannot decode), so it let the request through uninspected rather than break the page. The line names the reason, never the prompt; include it when you report the gap.
  • The extension disappeared after a restart. On Firefox a temporary add-on is removed on restart; on Chromium a load unpacked survives restarts but a profile reset drops it. This is inherent to a self-loaded extension — the governed control is managed force-install.

See also​