browser-cli/n8n-nodes-browser-cli/README.md

n8n-nodes-browser-cli

An n8n community node, published on npm as n8n-nodes-browser-cli, that controls a real, visible browser from your workflows via browser-cli.

browser-cli drives a running browser through a native-messaging host and a browser extension — it cannot be installed inside the n8n container. So this node speaks the browser-cli serve protocol directly: a length-framed TCP connection authenticated with an Ed25519 key, with request/response bodies encrypted end-to-end via an ML-KEM-768 (post-quantum) key exchange — the same wire protocol the browser-cli --remote client uses.

n8n workflow ──TCP (Ed25519 + ML-KEM-768)──▶ browser-cli serve (remote host) ──▶ browser

Because the payloads are end-to-end encrypted, the endpoint is safe to expose on an untrusted network without a TLS proxy in front of it.

Remote setup (on the browser machine)

Install browser-cli, register the extension, trust your n8n key, then start serve opening exactly the command tiers you need (it is safe-only by default):

uv tool install real-browser-cli
browser-cli install brave            # one-time: register the extension/native host

# On the n8n side, generate a client key and print its public key:
browser-cli auth keygen -o n8n_key.pem

# On the browser machine, trust that public key (optionally scope its policy):
browser-cli auth trust <pubkey-hex> --allow-control

# Expose the browser. Open only what your workflow needs:
browser-cli serve --host 0.0.0.0 --port 8765 \
  --authorized-keys ~/.browser_cli/authorized_keys --allow-read-page --allow-control

Paste the contents of n8n_key.pem into the n8n credential.

n8n credential — "Browser CLI API"

Field	Description
Host	host of the serve endpoint, e.g. browser-host.example
Port	serve TCP port (default 8765)
Ed25519 Private Key	PKCS8 PEM from browser-cli auth keygen (empty only for --no-auth loopback)
Browser Alias	optional _route target — required if the endpoint serves multiple browsers
Server Public Key/Fingerprint	pinned browser-cli serve identity (SHA256:... fingerprint or 64-char server public key hex)
Allow Unknown Server Identity	disables SSH-style server pinning; use only for loopback/dev
Use TLS	wrap the connection in TLS (only for a TLS-terminating proxy; the protocol is already encrypted)
Ignore SSL Issues	when TLS is on, accept a self-signed proxy cert

Server identity pinning

Recent browser-cli serve versions advertise a persistent Ed25519 server identity in the challenge frame. The n8n node verifies the challenge signature and compares the key against the credential's Server Public Key/Fingerprint field, similar to SSH known_hosts.

On a trusted machine, pin the server once with the Python CLI and copy the fingerprint into the n8n credential:

browser-cli remote trust-host browser-host.example:8765
browser-cli remote known-hosts

If the server key changes, the node fails with REMOTE SERVER IDENTITY CHANGED. Only enable Allow Unknown Server Identity for local/dev endpoints where you explicitly do not want pinning.

Operations

Every operation maps to one raw browser-cli command, each subject to the server policy tier noted below.

Resource	Operation	Command	Server flag needed
Tab	List / Query / Get / Count / Filter / Active in Window	tabs.list / tabs.query / tabs.status / tabs.count / tabs.filter / tabs.active_in_window	safe (default)
Tab	Get HTML	tabs.html	--allow-read-page
Tab	Open / Close / Activate / Move / Navigate To / Reload / Hard Reload / Back / Forward	navigate.open / tabs.close / tabs.active / tabs.move / navigate.to / navigate.reload / navigate.hard_reload / navigate.back / navigate.forward	--allow-control
Tab	Mute / Unmute / Pin / Unpin / Dedupe / Sort / Merge Windows	tabs.mute / tabs.unmute / tabs.pin / tabs.unpin / tabs.dedupe / tabs.sort / tabs.merge_windows	--allow-control
Tab	Screenshot	tabs.screenshot	--allow-dangerous
Page	Get Info	page.info	safe (default)
Page	Extract Text / Links / Images / HTML / Markdown / JSON	extract.*	--allow-read-page
DOM	Query / Text / Attribute / Exists	dom.query / dom.text / dom.attr / dom.exists	--allow-read-page
DOM	Click / Type / Select / Hover / Focus / Check / Uncheck / Clear / Submit / Scroll / Key	dom.*	--allow-control
DOM	Eval	dom.eval	--allow-dangerous
Group	List / Query / Tabs	group.list / group.query / group.tabs	safe (default)
Group	Count / Create / Add Tab / Move / Close	group.count / group.open / group.add_tab / group.move / group.close	--allow-control
Window	List	windows.list	safe (default)
Window	Open / Close / Rename	windows.open / windows.close / windows.rename	--allow-control
Session	List / Save / Load / Remove / Export / Diff / Auto Save	session.*	--allow-control
Storage	Get / Set	storage.get / storage.set	--allow-dangerous
Performance	Status	perf.status	safe (default)
Extension	Info / Capabilities	extension.info / extension.capabilities	safe (default)
Extension	Reload	extension.reload	--allow-control
Client	List	clients.list	safe (default)
Command	Execute	any command name + JSON args	per command

Command → Execute is the escape hatch: any command string the server policy allows (tabs.query, session.save, windows.list, …) with a JSON args object. Use it for anything the typed operations don't cover.

Note: serve returns the raw command result (no SDK post-processing). extract.markdown therefore returns the page payload as the extension hands it back, not the CLI's rendered Markdown. For clean text use Extract Text.

Tab → Filter / Count URL Pattern: matched against the full tab URL. A plain string is a case-sensitive substring (twitch.tv); a pattern containing * or ? is a glob (twitch.tv/*, *.twitch.tv). Glob needs the serve-side extension at 0.16.4+; older extensions treat the whole pattern as a literal substring, so twitch.tv/* matches nothing there — use twitch.tv instead.

Develop / build

cd n8n-nodes-browser-cli
npm install                 # add --ignore-scripts if a transitive native dep
                            # (isolated-vm) fails to compile on your Node version
npm test          # pure unit tests: command mapping + crypto known-answer vectors
npm run build     # tsc -> dist/, copies the icon

Install the published package in n8n as a community node using the package name n8n-nodes-browser-cli, or symlink dist/ into ~/.n8n/custom for local testing.

License

PolyForm Noncommercial License 1.0.0 — same as browser-cli.