Skip to main content

​
Install and requirements

Requires Node 22.14.0 or newer and an installed stable Google Chrome on Linux or macOS. Linux needs a graphical display and a working Chrome sandbox. Windows browser hosting and secure file/secret output are not supported. Install the current 0.3.7 CLI release:
Installation does not download or launch Chrome. Agent-only help/file/secret/forward commands do not need a display or Chrome.

​
Start and pair

The runtime owns a separate Chrome profile. Named profiles persist sign-ins; ephemeral profiles are explicit and cleanup is limited to owned files. Do not point it at a normal Chrome profile or copy daily-driver cookies. Concurrent profile owners are rejected. Local process/profile access is outside the security boundary: this is not a sandbox against malicious software running as you. Open the printed device approval URL in your browser, verify its hostname and request name, sign in and explicitly approve. Managed uses GitHub; community uses local bootstrap or configured OIDC. Device requests expire after ten minutes. The random proof held by the CLI—not the approval URL alone—redeems the credential. Restart pairing if expired. The native connection credential is distinct from a dashboard-created MCP client token. Protect credential files; do not supply literal credentials in arguments, URLs, tickets or chat. Device pairing is the supported setup; there is no manual connection-token import.

​
Multiple local browsers

Each browser needs a different profile name. You can run separate browser start commands in separate terminals today:
CLI 0.3.7 and newer also accept repeated --profile flags to start two or more browsers in one foreground command:
Each profile has isolated Chrome data/sign-ins, pairing credentials, local controls and a separate browser registration. Approve each new profile’s labeled pairing link and configure its own dashboard MCP URL/token. No profile’s credential is shared with another. Use status, pause, resume or stop with one --profile to control only that browser. Closing or stopping one browser leaves the others running. Ctrl-C in the group’s terminal closes every browser launched by that command. The command stays running until all its browsers stop. A launch/runtime failure cancels the group and waits for cleanup; an existing profile owner is never taken over. --server, --chrome-path, --ephemeral and --live-view apply to every profile in a grouped launch. For different options or independent CLI lifetimes, use separate terminals. With --ephemeral, each logical name still selects its own pairing and local controls, but its Chrome data is throw-away. No --profile means default. Repeated names are rejected; a busy profile requires a different name, not deleting its lock. Local control and recovery commands accept only one profile at a time.

​
Visible local controls

Use another local terminal with the same profile:
Remote agents cannot resume a local pause. Use the CLI status command to check whether the browser is paused or running. Revoking an MCP token removes that client. Rotating the browser credential invalidates its saved credential and disconnects the runtime. For recovery, stop it, revoke/delete the old registration as appropriate, identify and remove only the exact private credential file for that server/profile, then start and approve a new pairing. The new registration needs new MCP tokens. Do not remove the Chrome profile, directory trees or unrelated credential files. Deleting the registration removes its access credentials, not your personal Chrome files. The runtime stays in the foreground and uses private-pipe Chrome control: Ctrl-C or stop closes its Chrome. Signal handlers are active from the beginning of startup. Ctrl-C during startup cancels remaining work, waits for an in-progress bounded Chrome launch, and then closes resources already acquired. Repeated Ctrl-C or other termination signals wait for the same cleanup instead of bypassing it. Pairing waits are cancelled. If one cleanup stage fails, the other independent safe stages are still attempted and the errors are reported afterwards. There is no detach/reattach mode, and a restart creates a new runtime instance rather than attaching to an old Chrome process. Stop before replacing CLI binaries, then restart the same named profile to retain sign-ins. Live view requires explicit local --live-view on browser start and is off by default. Relay reconnect, CLI restart and Chrome restart are different events. A reconnect never authorizes replaying uncertain clicks, form submissions, scripts or file attachments. Stale document refs/choosers must be reacquired. Forwarding and bulk streams do not transparently resume after disconnect. Read status and inspect results before retrying.

​
Explicit crash-artifact recovery

A crash can leave a named profile’s runtime lock and local control socket behind. They are deliberately not removed automatically, and startup will not delete or take over an existing path. First stop the prior CLI and its dedicated Chrome and prevent concurrent startup or manual artifact changes. Then run the operator command with the logical profile name, never a filesystem path:
Recovery is limited to Linux and macOS. On success it removes only a verified stale control socket and runtime lock, in that order. The Chrome profile and its sign-ins, downloads, run data, and Chromium singleton artifacts are preserved. If no recovery artifacts exist, it leaves the profile unchanged. Recovery is intentionally conservative. It refuses rather than guesses when the recorded PID is live or may have been reused, the owner or process scan is uncertain, a possible profile process survives, a control listener is live or cannot be proven stale, ownership or private permissions are unsafe, an ancestor or artifact is a symlink or other unexpected type, an artifact changes during checking, Chromium ownership is foreign or unrecognized, or a socket is orphaned without matching lock provenance. Do not work around refusal by deleting paths blindly or creating a replacement lock. There is no automatic crash cleanup and no reattachment to the old Chrome process. If recovery refuses, retain the exact paths printed in the error and investigate the prior owner. Only a qualified operator who can independently prove exact path provenance, private ownership, unchanged artifact identity, and absence of every possible owner or listener should consider manually removing that exact stale socket; never remove profile directories or Chromium singleton files.

​
MCP client setup

Create an expiring token for the connected browser in the dashboard. Store the token in your client’s secret settings and use its Streamable HTTP transport:
Client configuration keys vary. Token scope is broad browser control, not single-tab or read-only. Start with browser_list_tabs, then a temporary tab on https://example.com. File staging and secret export are separate explicit capabilities; see data and secrets.

​
Update safely

The dashboard shows native version, protocol, advertised capabilities and an update-required indicator. Protocol 3 is the native contract; unsupported commands fail closed. Stop the runtime, install a compatible CLI version, then restart the same named profile. Do not delete credentials or profiles as an update mechanism. There is no silent unrestricted auto-updater. Chrome itself should be maintained through its normal trusted update channel.

​
Troubleshooting

  • Offline: check local status, approval, exact server URL, TLS and proxy WebSocket support.
  • Update required: use a verified compatible CLI/server pair; do not bypass capability checks.
  • Profile busy: use a different --profile to launch another browser, or stop the owning runtime; do not delete locks or another process’s files blindly.
  • Control-plane or privileged page rejected: expected; use an ordinary website that you are authorized to access.
  • Unknown action outcome: inspect before deciding any next action; never blindly replay.
  • Clipboard/live view unavailable: these are capability/platform dependent and require local permission/opt-in, not automatic fallback.
For support use support@browser-mcp.click, or your self-hosted operator. Include version and redacted failure metadata, never tokens or private page content.