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    # start 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. It matters when you want to connect somewhere specific — see Remote browser below — or control the session lifecycle yourself.

Persisting auth across sessions

Logging in every run is slow. bl storage exports the browser's cookies, localStorage, and sessionStorage to JSON, and bl storage restore loads them back — so you can authenticate once and reuse that state later.

# Log in once, then save the resulting state
bl go 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 -o auth.json

# In a later run, restore the state and skip the login
bl storage restore auth.json
bl go https://app.example.com/dashboard

Without -o, bl storage prints the state as JSON to stdout, so you can capture it however you like.

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 go 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 daemon & the visible browser — how the browser stays warm across commands.