Skip to main content
A developer browser is a separate Chrome, Brave, Firefox or Zen instance the companion launches and controls directly. Chrome and Brave use CDP; Firefox and Zen use WebDriver BiDi. They can run alongside your connected extension browsers. See Modes for when a launch is allowed and Firefox and Zen coverage for their limits.

​
Contexts

Every developer browser is a context with a name. browser_session actions: Contexts run in parallel and are independent browsers: separate cookies, storage and windows. Use them for “work” versus “personal” logins, cross-browser checks, or different proxies. Tab IDs are unique across developer contexts and connected extension browsers. browser_tabs lists the browser and context for each developer tab. A context name can belong to only one running browser at a time; use names such as chrome, brave, firefox and zen when running them together. To open another tab in a specific developer browser, pass mode: "dev" and its context to browser_tabs with action: "new". For existing tabs, use the returned tabId. See using multiple browsers for examples.

​
Profiles

Profiles persist between launches: "chrome" and the compatibility choice "chromium" use the same Chrome profile paths. BROWSPARK_PROFILES also changes the parent of the .brave, .firefox and .zen directories. Each browser keeps its own saved profiles. Log in once and the session is there next time. delete wipes a stopped profile; pass both its context and browser to select it explicitly.

​
Launch options

  • headless: true runs without a window. Chromium browsers support the live view; use screenshots on Firefox and Zen.
  • devtools opens Chromium DevTools on every tab (default on unless headless) so you can follow the agent in the standard panels. Firefox and Zen reject devtools: true.
  • proxy takes http://host:port or socks5://host:port and applies to the whole context.
  • extensions loads unpacked extension directories in Chromium developer browsers through the protocol after launch. Firefox and Zen reject this option. Availability depends on the selected Chromium build.
  • args appends command-line switches for the selected browser.
  • browserPath picks the executable for the selected browser. BROWSPARK_CHROME, BROWSPARK_BRAVE, BROWSPARK_FIREFOX and BROWSPARK_ZEN provide corresponding defaults. Legacy chromePath and firefoxPath options remain supported.
  • downloadDir selects the browser’s download directory. browser_status reports the active directory. The default is ~/.browspark/downloads/<browser>/<context>; the compatibility choice "chromium" retains ~/.browspark/downloads/<context>. See Firefox and Zen coverage for browser differences.

​
Live view

Running Chromium contexts print a live-view URL in browser_status:
Open it in any browser to see a JPEG screencast of that tab with click-through mouse and keyboard control. Click the image to type into it, press Escape to release. It is the way to watch a headless run or to intervene, for example to solve a login step yourself.

​
CDP endpoint

For Chrome and Brave, browser_status and the launch result also print the browser’s CDP WebSocket endpoint. Playwright and Puppeteer can attach to it:
Your script and the agent then share the same browser and tabs. Firefox and Zen endpoints speak WebDriver BiDi and cannot be used with connectOverCDP.

​
Cleanup

The companion closes every developer browser it launched when it exits (Ctrl-C, stdin closing, SIGTERM). browser_session {action: "close", all: true} does it on demand.