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
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

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	tabs.list	safe (default)
Tab	Open	navigate.open	--allow-control
Tab	Close	tabs.close (ids / inactive / duplicates)	--allow-control
Tab	Get HTML	tabs.html	--allow-read-page
Page	Get Info	page.info	safe (default)
Page	Extract Text / Links / Images / HTML / Markdown	extract.*	--allow-read-page
DOM	Query	dom.query	--allow-read-page
DOM	Click / Type	dom.click / dom.type	--allow-control
DOM	Eval	dom.eval	--allow-dangerous
Client	List	clients.list	safe (default)
Command	Execute	any command name + JSON args	per command
Gateway	Health	pings with tabs.list	safe (default)

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.

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.