Sessions, storage & auth

A session is browserlane's connection to a browser. Most of the time you don't manage it explicitly — a browser command starts one for you. But controlling the session directly is useful for remote browsers and for persisting login state.

Starting and stopping a session

bl start is the explicit lifecycle command: with no arguments it launches (or ensures) a local browser; with a WebSocket URL it connects to a remote BiDi endpoint (see Remote browser below). bl stop closes the session's browser.

bl start    # start (or ensure) a local browser session
bl stop     # stop the browser session (and the daemon)

You rarely need bl start for local work, since any browser command launches a session on demand — including bare bl open (and its aliases go / goto / navigate), which lazily launches a local browser to about:blank when you don't give it a URL. Reach for bl start explicitly when you want to connect somewhere specific or control the session lifecycle yourself.

Persisting auth across sessions

Logging in every run is slow. bl storage save snapshots the browser's cookies, localStorage, and sessionStorage to a named local snapshot, and bl storage load restores it — so you can authenticate once and reuse that state later.

# Log in once, then save the resulting session storage
bl open https://app.example.com/login
bl fill "input[name=email]" "user@example.com"
bl fill "input[name=password]" "secret"
bl click "button[type=submit]"
bl wait url "/dashboard"
bl storage save auth

# In a later run, restore the snapshot and skip the login
bl storage load auth
bl open https://app.example.com/dashboard

Manage saved snapshots with bl storage list, bl storage show <name> (redacted metadata only), and bl storage delete <name>. Move a snapshot between machines with bl storage export <name> -o <path> and bl storage import <path> --name <name>.

Remote browser

bl start with a URL connects to a remote browser over a BiDi WebSocket endpoint instead of launching one locally:

bl start ws://remote-host:9515/session
bl open https://example.com
bl map
bl stop

If you don't pass a URL, bl start checks the BROWSERLANE_CONNECT_URL environment variable before falling back to a local launch. Set BROWSERLANE_CONNECT_API_KEY to send an Authorization: Bearer header with the connection:

export BROWSERLANE_CONNECT_URL=wss://cloud.example.com/session
export BROWSERLANE_CONNECT_API_KEY=my-api-key
bl start    # connects using the env vars

Related

• bl start, bl stop, and bl storage in the CLI reference.
• The warm browser & the visible window — how the browser stays warm across commands.