1.4.0: Authentication and local storage

Sam March — Tue, 17 Feb 2026 02:50:00 +0000

I'm thrilled to announce the 1.4.0 release for BlitzBrowser. This new version contains a new security layer for public deployments and user data storage on local disk by default.

Until now, persisting user data required setting up an S3 compatible provider. It is great for scale and cloud deployment, it added friction for local development and integration tests. Deploying into the cloud required an external way to restrict access to the browsers. I added a built-in authentication layer on the dashboard and on BlitzBrowser. You can now deploy BlitzBrowser on the internet securly.

User Data Storage on Local Disk

In 1.4.0 you are no longer forced to use S3 (like AWS, Cloudflare R2 or RustFS) to save your browser user data. You can now mount a local directory directly to your Docker container to persist them.

Simply map a volume to /blitzbrowser/user-data and your user data will persist between container restarts.

services:
  blitzbrowser:
    image: ghcr.io/blitzbrowser/blitzbrowser:latest
    ports:
      - "9999:9999"
    volumes:
      - ./user-data:/blitzbrowser/user-data
    shm_size: "2gb"
    restart: always

Find all the details about the user data storage.

Built-in Authentication

Previously BlitzBrowser was open to anyone who could reach it. Version 1.4.0 introduces built-in authentication to control who can access the browsers and the dashboard. BlitzBrowser and the dashboard can now be configured to use an API key and an authentication key.

Configuration

BlitzBrowser: All CDP and HTTP connections must provide a valid API_KEY. You can pass the API key by:
- HTTP header: x-api-key: ${API_KEY}
- Query parameter: apiKey=${API_KEY}
Dashboard: Users must provide the AUTH_KEY to log in. The dashboard uses the BLITZBROWSER_API_KEY to connect to the API.

For detailed setup instructions, please refer to the dashboard configuration and the BlitzBrowser configuration pages.

How I built Live View for browsers running in Docker

Sam March — Thu, 05 Feb 2026 14:50:00 +0000

Debugging browsers in docker is usually a blind experience. You have to screenshot or log every step to see what happens. That's why I built the Live View feature.

While updating the tutorial using Crawl4AI, Ollama and BlitzBrowser to run a self hosted AI crawler, I had issues. It wasn't extracting the data I expected and restarting the script every time to debug was painful. I wished to see the browser in real time to understand why.

My first idea was to create a video stream of the browser, but I remembered my first issue requesting a real time interaction with the browser. I started to look for an equivalent of the RDP protocol on Linux. I discovered the VNC (Virtual Network Computing) protocol and the NoVNC javascript client.

Under the Hood

To see the browser running in docker, I needed to bridge the gap between the Linux virtual display and the web browser. This is the stack used.

Display: First the browsers are run in a virtual display. The virtual displays are managed by x11 and each browser has its own display. I'm using Fluxbox as a window manager.
VNC Server: If the Live View feature is enabled, the browser will be started with a x11vnc server to create the remote access. It will be accessible from a TCP port on the localhost network.
Websocket-to-TCP bridge: To connect to the VNC server from a web client, the web server exposes the websocket endpoint /browser-instances/:browser_instance_id/vnc. When a client connects to the endpoint, it creates a TCP connection to the VNC server. It will bridge the websocket and the TCP socket by transmitting all the data received from the TCP socket to the websocket and all the websocket data to the TCP. This is the code if you are interesting.
Frontend: The NoVNC client to connect the VNC server through the websocket. Once the connection is established, NoVNC streams the virtual display and transmit all the interactions done by the user to the server.

The result

Once the Live View feature was functionnal, I debugged my AI crawler in seconds. The website was detecting my bot, I had no stealth precaution implemented, and it was hiding some data. I changed the tutorial to use the developer doc and it was working perfectly.

Conclusion

If you ever need to debug your headless browsers, I hope this feature will help you to debug faster.

DEV Community: Sam March