Skip to main content
The developer browser is a Chrome the companion launches and controls directly. It exists for capabilities Chrome withholds from extensions; see Modes for when it is allowed to start.

​
Contexts

Every developer browser is a context with a name. browser_session actions: Contexts run in parallel and are independent browsers: separate cookies, storage, extensions and windows. Use them for “work” versus “personal” logins, for a clean profile next to a populated one, or to run several scrapers behind different proxies at the same time. Tab ids are unique across contexts, so browser_tabs shows all of them in one list with their context name.

​
Profiles

Profiles persist between launches: Log in once and the session is there next time. delete wipes it.

​
Launch options

  • headless: true runs without a window. Watch and control it through the live view.
  • devtools opens Chrome DevTools on every tab (default on unless headless) so you can follow the agent in the standard panels.
  • proxy takes http://host:port or socks5://host:port and applies to the whole context.
  • extensions loads unpacked extension directories. They are loaded through the protocol after launch, which is what current Chrome versions require.
  • args appends raw Chrome switches.
  • chromePath or BROWSPARK_CHROME picks the executable when auto-detection finds the wrong browser.
  • downloadDir overrides ~/.browspark/downloads/<context>; browser_download reports files landing there.

​
Live view

Every running context prints 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

browser_status and the launch result also print the browser’s WebSocket endpoint. Playwright and Puppeteer can attach to it:
Your script and the agent then share the same browser and tabs.

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