open_session

open_session

Start a browser session. Do this first.

MCP tool	open_session
HTTP	POST /browser/open

This is the only place a browser is created, and the only place its settings can be chosen, so it is never done implicitly for you.

Called with nothing, it carries on where this session left off: the same browser, the same window, back to the page it was last on. So after a browser is reaped or ended, a bare open_session() is usually right.

Safe to call while you already have a browser: the one you are holding is ended for you first, so you never need to close before opening. That is how you switch browser — open_session(browser="firefox") — and the files the old browser had go with it, because the Grid keeps them per browser and deletes them with it.

browser is "chrome" (the default) or "firefox". Every other tool works the same on either, so pick Firefox only when the task is about Firefox — checking a rendering difference, or a site that treats the two differently. A session cannot change browser later: open another one.

Set width and height when layout matters — the headless default is narrow and varies between Grid nodes. page_load_timeout bounds how long a navigation may hang; without one a stuck page holds a scarce Grid slot until the Grid reaps it.

The returned session_id is what a stateless caller passes to every later call. If this server is holding the browser for you, it is returned for information and you should NOT pass it back — read the session://current resource if you are unsure which of the two you are.

Parameters

Name	Type	Required	Default
url	string	no	—
browser	string	no	—
width	integer	no	—
height	integer	no	—
page_load_timeout	integer	no	—
script_timeout	integer	no	—

Returns

Field	Type	Notes
session_id	string	Pass this to every other call.
browser	string	The browser this session is running.
url	string	Current URL after the action.
title	string	Page title after the action.
width	integer	Window width in use.
height	integer	Window height in use.
settings	object	The settings this session actually opened with, after the server default / client default / explicit cascade.

Errors are 400 for a bad argument, 401 without a token, 500 when the Grid refuses. Over MCP the same failures arrive as a tool error.

Example

MCP

open_session()

HTTP

curl -X POST $SELENIUM_FLOW/browser/open \
  -H "Authorization: Bearer $TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "session_id": "…"
  }'

Chrome or Firefox

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 session cannot switch browser. To compare the two, open one session per browser and keep both ids. session://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 session, 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 (DEFAULT_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