Skip to main content

Live Debugger

Local and Hosted Live Debuggers function differently

The Live Debugger described on this page is a tool available on self-hosted containers. Our hosted Live Debugger (accessible from your account page) is a standalone tool that does not debug sessions you run from your code—it only works within that sandbox. For debugging approaches using your scripts running outside of the Live Debugger, we recommend using either the Hybrid feature in v2 or the BrowserQL Editor.

Debugging scripts for headless browsers is often the most frustrating and time-consuming part of the development cycle. Internal IDE and runtime debugging tools have many limitations for external processes, and taking screenshots at every step is only effective to a certain extent. External debugging libraries are also inconvenient to set up and clean up.

At Browserless, we want the headless browser development (and production) experience to be an effortless task, and that's why we ship a Live Debugger with our Chromium Docker images. Key features include:

  • Editor with syntax highlighting and auto-completion
  • TypeScript support
  • Visual screencast of the browser that you can interact with
  • Browser DevTools integration
  • File downloading for testing PDFs/PNGs
  • Control over browser-specific parameters (headless, stealth, etc.)
  • Tab-based layout with code-saving capabilities
  • Save your code to disk as a Node.js project

Inside your Browserless account, you will see an option in the menu linking to the debugger, under the Resources section:

Account Menu

And you will see the Live Debugger:

Account Menu

There you will be able to connect to your worker's websocket endpoints, set custom launch flags, and configure session parameters.

Alternative Debugging Approaches​

1. Hybrid Feature in v2​

For libraries like Puppeteer and Playwright, we recommend using our Hybrid automation feature which allows you to:

  • Stream remote headless browsers to users via a shareable URL
  • Detect when CAPTCHAs are found on the page
  • Allow human intervention in automation workflows
  • Continue automation after human interaction is complete

2. BrowserQL Editor​

For real-time session viewing and debugging, we recommend using the BrowserQL Editor, which provides:

  • Live view of the browser session in the right panel
  • Built-in documentation and debugging tools
  • Ability to create and test queries before integrating them into your code
  • Advanced session settings and configuration options

To access the BrowserQL Editor:

  1. Log into your Browserless account at account.browserless.io
  2. Navigate to the BQL section in the sidebar menu, or
  3. Go directly to https://account.browserless.io/bql

For more information about BrowserQL and its features, see our BrowserQL documentation.