Remote & multi-page

Two related needs come up once your automation grows past a single local tab: driving a browser that lives somewhere else (a cloud grid, a container), and working across multiple pages at once. browserlane handles both.

Connect to a remote browser

By default bl start launches a local Chrome. Pass a URL and it instead connects to a remote browser over a WebDriver BiDi WebSocket endpoint:

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

Once connected, every command works exactly as it does locally — the only difference is where the browser runs.

Connect via environment variables

If you don't pass a URL, bl start checks the BROWSERLANE_CONNECT_URL environment variable before falling back to launching a local browser. Set BROWSERLANE_CONNECT_API_KEY to send an Authorization: Bearer header with the connection — useful for hosted browser services that require a key:

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

This is the convenient form for CI: set the two variables in the environment and every bl command in the job targets the remote browser without repeating the URL.

Work across multiple pages

A session can hold several open pages. List them, open new ones, and switch between them — commands always act on the current page.

bl pages
# [0] https://example.com
# [1] https://docs.example.com

Open, switch, close

bl page new https://docs.example.com   # open a new page (and navigate)
bl text "h1"                           # acts on the new page — it's now current

bl page switch 0                       # switch back to the first page by index
bl page switch docs.example.com        # …or switch by URL substring

bl page close 1                        # close page at index 1
bl page close                          # close the current page

bl page new with no URL opens a blank page; bl page switch takes either a numeric index (from bl pages) or a substring of the page's URL; bl page close defaults to the current page when you omit the index.

A two-page workflow

Open a reference page alongside your main one, read from it, then return:

bl go https://app.example.com
bl page new https://docs.example.com   # second page, now current
bl text "h1"                           # read something from the docs
bl page switch 0                       # back to the app
bl map                                 # carry on with the app

Related

• bl start, bl stop, bl page, and bl pages in the CLI reference.
• Sessions, storage & auth — sessions and the remote-connect flags in depth.
• The daemon & the visible browser — how the session stays warm between commands.