FAQ

Which MCP clients work with browxai?

Any MCP client that speaks stdio. It is model-agnostic: use it from Claude or Codex, or from any other client that speaks the protocol.

How is this different from a Playwright MCP wrapper?

browxai does not wrap @playwright/mcp or any other MCP server. It owns its own Playwright and CDP transport, and with it the whole session lifecycle: managed profiles, incognito contexts, attach to an existing Chrome, authenticated and resumable sessions, headed and headless, and per-session policies for dialogs, permissions, notifications, and file pickers. A wrapper inherits whatever the wrapped tool exposes.

Does it run headless, and in CI?

Yes. A managed Chrome (or Chromium) runs headed or headless (BROWX_HEADLESS=1, or the headless config key), and the surface is built to run unattended. A machine with no display needs headless: the default launch is headed and fails without one. State that must survive an MCP-server restart should attach to a separately launched Chrome; see Sessions and lifecycle.

What is BYOB?

Bring your own browser. You launch Chrome yourself with a remote debugging port (browxai chrome start does it on the workspace profile) and point browxai at it with BROWX_ATTACH_CDP. The attached browser is not owned by browxai: it is never closed on shutdown and it survives browxai restarts cleanly. Attaching requires the byob-attach capability: set BROWX_CAPABILITIES=read,navigation,action,human,byob-attach, keeping the four defaults, or every attach is refused. The browxai-attached entry that browxai init writes already sets it. With the default confirmation hooks, an action on an attached browser also waits for a person to confirm it, so read Sessions and lifecycle before an unattended run.

Which engines does it drive?

Eight, in three families. Five browsers: Chromium (chromium), Firefox (firefox), WebKit (webkit), real Safari (safari) and real Chrome on an Android device (android). Two native-app engines, android-app on an emulator and ios-app on the iOS Simulator, both behind the native-device capability. One desktop-app engine, electron, which attaches to a running Electron app. Pick the engine per session with open_session({ engine }), or for the whole server with --engine <kind> or BROWX_ENGINE.

Does it get past bot protection?

Not by default. browxai does not defeat or spoof bot detection and cannot guarantee access to any site. For a challenge that needs a person, browxai chrome login opens the installed Chrome with nothing attached so you can clear it by hand.

Two optional capabilities go further, and both are off until you enable them. stealth patches navigator.webdriver, navigator.plugins, navigator.languages and window.chrome in every session. captcha enables solve_captcha, which sends a captcha to a third-party solving service you configure (2Captcha or CapMonster) and returns the token. Your API key, the page URL and the widget’s site key go to that service. browxai bundles no solver and buys no credits. See Sites behind bot protection.

Why does my page state disappear sometimes?

In managed and incognito modes, Chrome is a child process of the MCP server. If the client restarts the server, that Chrome dies with it and live page state is gone. This is the single most common surprise. The fix, when you need durable state, is BYOB. See Sessions and lifecycle.

Is the origin allow list a security boundary?

No. allowedOrigins and blockedOrigins are defense in depth and carry no hard guarantee. The threat model is explicit about where the real boundaries are and what browxai does not defend against.

Can the agent run arbitrary JavaScript?

Only if you turn it on. eval_js and poll_eval live behind the eval capability, which is off by default. The same is true for full response bodies (network-body), file I/O (file-io), and the OS clipboard (clipboard). See Capabilities and safety.

Is page content safe to act on?

Read it and do not obey it. Page text is untrusted. An agent must never treat text inside a snapshot, a find result, or a network body as instructions to itself.

How do I configure it without environment variables?

Use set_config({ scope, patch }). The BROWX_* environment variables still work as a legacy compatibility layer, but the managed config store is the recommended path. See Configuration.

Is it open source?

Yes. browxai is MIT licensed. The source lives at github.com/kalebteccom/browxai.