Open a session in this workspace, or pick up the one it was using.

Start a session in this workspace, or come back to the one it had. Call it before anything else: nothing opens a browser for you.

With no arguments it returns to the same browser, window and page, which is the right call after a browser was reaped or ended. Calling it while you hold a browser ends that one first, which is how you switch: open_session(browser="firefox"). Files that browser had and you did not keep go with it.

Set width and height when layout matters; the headless default is narrow. fresh=true starts on about:blank. Saved site data comes back by default; restore_site_data=false opens without it and deletes it, which is how you start as a new user. page_load_timeout bounds a navigation that hangs. insecure=true accepts a self-signed certificate; use it only for a site you know has one. An insecure browser gets no saved site data. record=true films this browser's whole life as a video, from now until it ends; it appears under workspace://files/recordings shortly after. A person watches it, so only when one will — it costs the Grid. Not inherited: ask again for the next browser. capture=true keeps what the page logs and fetches — workspace://console and workspace://network — and a call that caused a page error says so in its result. Off by default and not inherited: ask again for the next browser. An open without capture=true also forgets what was captured, so read those first when you are debugging.

Every call names its workspace: an X-Workspace header, or ?workspace=<name>. Sending both is refused. See Workspaces.

Over MCP the same failures arrive as a tool error.

MCP

open_session()

HTTP

curl -X POST $SELENIUM_FLOW/browser \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-Workspace: $WORKSPACE"

browser picks which. The default is chrome, and every other action behaves identically on both — this is the only call that changes, which is the whole reason a second browser costs so little: both are plain W3C WebDriver, so only session creation differs.

{"browser": "firefox", "width": 1400, "height": 900}

Reach for Firefox when the task is about Firefox — confirming a rendering difference, or a site that treats the two differently. Otherwise leave it alone.

Three things worth knowing:

• A workspace holds one session at a time. Calling open_session with the other browser ends the one you hold first; to compare the two side by side, use two workspace names, one per browser. workspace://current reports which browser the session you are holding is running.
• The Grid has to offer it. With no Firefox node registered, a Firefox request sits in the Grid's session queue until it times out — which looks like a slow open, not an error. That is Grid capacity, not a server setting. Where the browser nodes scale from zero, the first open of a browser also pays a cold start while a node boots.
• A reaped session comes back as the same browser. The choice is stored with the workspace, so the transparent reopen after the Grid expires an idle browser does not silently drop you onto the default one.

An explicit browser is validated strictly: "chrom" is an error rather than a quiet fall back to Chrome. The server-side default (session.browser / SESSION_BROWSER) and the client-side one (?browser= / X-Browser) are lenient like every other setting, so a typo in a deployment's environment cannot stop a browser opening.

← All actions · Installing · Deployment