Skip to content

session settings

Dr K edited this page Nov 14, 2026 · 3 revisions

Session settings

open_session is the one call that makes a browser, and it is where a browser's shape is chosen: which browser and version, its window, its two timeouts, whether it accepts a bad certificate, runs headless, is recorded or captured, and any raw WebDriver capability nothing else covers. This area holds what each setting is called on every surface, where its value comes from when several are given, what a workspace remembers, how the capabilities sent to the Grid are built, and what a refused open says.

Use cases

  • An operator sets session.browser, session.version and session.capabilities once, so every new browser lands on the right Grid node class without an agent knowing about it.
  • A client pins its own browser or window in its connection config (?browser=, Sf-Browser) and never passes them in a call.
  • An agent opens Firefox 152 at 1400 by 900, and a browser the Grid reaps comes back the same.
  • An agent opens headless=true for a fast task and is told at once that it cannot also record.
  • An agent adds a Chrome flag through raw capabilities, and a key a named option controls is refused with the option to use.

Neighbours

SET-1. The record, its store and the reopen after a reap are in workspaces-and-sessions.md. Site data restored into a new browser is in site-data.md. The live view that a headless browser lacks is in live-view-and-control.md. The tool, route and header machinery (the Sf- names, X-Workspace, the request schema) is in surfaces.md. How the Session tab draws what this file serves is in admin-ui.md. Recording and capture themselves are in workspace-files.md and capture.md; this file holds only how they are asked for. Configuration loading is in config.md.

The settings

SET-2. An open takes the settings in the table. url, fresh and restore_site_data are arguments of the call, not settings, and are never remembered.

Setting Argument Query Header Config key Value
browser browser ?browser= Sf-Browser session.browser chrome (default) or firefox
version version ?version= Sf-Version session.version a string, or latest
width width ?width= Sf-Window-Width session.width integer
height height ?height= Sf-Window-Height session.height integer
page_load_timeout page_load_timeout ?page_load_timeout= Sf-Page-Load-Timeout session.page_load_timeout seconds
script_timeout script_timeout ?script_timeout= Sf-Script-Timeout session.script_timeout seconds
insecure insecure none none none boolean
headless headless none none none boolean
record record none none none boolean
capture capture none none none boolean
capabilities capabilities none none session.capabilities (separate source, SET-27) object

The argument is a tool argument on /mcp and a body field of POST /browser. The config keys take the environment spellings SESSION_BROWSER, SESSION_VERSION and so on.

SET-3. A header wins over the query parameter of the same setting. A blank or unusable header falls through to the parameter, and a repeated header or parameter counts as its last value. A header or parameter outside the table is not a setting. The retired X- names are refused (SURF-10).

SET-4. No bound is checked on width, height or either timeout, by the server or by the config. A value the browser or the Grid cannot honour fails the open, which quits the browser it made.

SET-5. browser is the only setting whose bad value is refused everywhere it is explicit. An explicit browser that is not chrome or firefox (any casing, surrounding space dropped) is a ValueError, a 400 reading unknown browser 'x'; known browsers: chrome, firefox. A bad session.browser stops the server at load. A bad client default (a header or parameter) is ignored with a warning, so a typo in a connection config does not stop a browser opening. The MCP tool's schema takes only the lowercase names, and a blank browser there means unset.

SET-6. A client default or explicit value that cannot be read as the setting's type (a non-numeric width, say) is dropped with a warning and the setting reads as unset. An unset window or timeout leaves the browser's own default; selenium-flow invents no number for it.

Where a value comes from

SET-7. A setting's value is the first of these that names it, highest first:

  1. the call's own argument;
  2. what this workspace's caller passed to an earlier open;
  3. the client's default (header or parameter);
  4. the operator's config.

workspace/settings.py walks the layers, and each setting's winning layer is its source: config, client or caller. The call's argument and the workspace's memory are both caller.

SET-8. A workspace keeps only what a caller passed. The config and the client's defaults are read afresh at every explicit open_session, so a changed session.* value or a dropped header reaches the next open and never a browser already running. The workspace's record holds the resolved settings with a source for each key (set_by); an explicit open inherits only the keys whose source is caller.

SET-9. insecure, headless, record, capture and capabilities have no client or config layer. false is a value: insecure=false or headless=false beats a remembered true, and is remembered in its turn. {} is a value for capabilities and clears the remembered object.

SET-10. record and capture are never inherited by an explicit open: each is asked for again for the next browser. All other settings are.

SET-11. A call that passes version with no browser (other than latest) is stored with the browser in effect at that open as the caller's, so a later change of session.browser does not move the version onto the other browser.

SET-12. A version belongs to its browser. Walking the layers from the lowest, a layer that names a browser different from the one in effect drops every version from the layers below it. A version in that same layer stands. The same browser keeps its version. So session.version=152 with open_session(browser="firefox") asks for Firefox with no version.

SET-13. version="latest" (any casing) is a value: it beats a remembered, client or config version and is never sent to the Grid. version that is blank or only space reads as unset. Beyond that, version is any string; the Grid decides whether it has one.

SET-14. The window and the timeouts are WebDriver commands sent after the browser starts, not capabilities. Width and height are set together, and one given alone keeps the browser's other dimension. A timeout of 0 or unset sends no command. The window is set before the restore of site data and before the first page loads, so it holds for both.

SET-15. resize marks width and height as the caller's in the stored settings, so a resized window is carried over and replayed after a reap.

SET-16. Every setting takes effect at the next browser. Nothing here changes a browser that is already open, apart from resize (SET-15).

What a workspace remembers

SET-17. After a reap, the reopen replays the whole stored set, whoever set each value, and each keeps its source. A config value stays the config's, so the next explicit open still reads the config afresh. A browser never changes shape mid-task.

SET-18. The reopen drops record when recording is switched off on the server and capture when capture is, and replays them otherwise.

SET-19. The record also keeps, for the Session tab:

  • sent, the capabilities that browser's open sent with their sources (SET-31);
  • ran, the version, node name and live-view flag the Grid reported (browserVersion, se:containerName, se:vncEnabled; each null when absent);
  • ended, how the last browser ended.

A new browser clears ended. Ending a browser keeps sent, ran, the settings and their sources.

SET-20. A stored record whose set_by is missing, malformed or does not name exactly the keys of its settings reads with no settings and no browser. Its history, site data, sent and ran stay. The next call is told to call open_session, which starts from the config, the client and its arguments.

SET-21. fresh=true drops only the remembered page. The settings still come through the cascade, and an explicit url is never overridden by it.

Checks before a browser opens

SET-22. open_session validates before it ends the browser the workspace holds, so a rejected argument costs nothing. In order, it refuses: a person controlling the held browser (409); an explicit bad browser (SET-5) or a capabilities that is not an object, reading capabilities must be an object (400); record on a server with recording off (400); record with headless (SET-23); capture on a server with capture off (400); an owned key or malformed vendor block in capabilities (SET-28 to SET-30); a url that is not allowed (400).

SET-23. A headless browser cannot be recorded. record=true with headless in effect is a 400 that says where headless came from. Passed in this call: a headless browser draws nothing to film: record=true cannot be asked with headless=true. Remembered: this workspace's browser is headless, remembered from an earlier open: pass headless=false to record. A server with recording off says that first.

SET-24. A headless browser has no live view for as long as it lives. The live view's mint and socket refuse it with this browser is headless: it has no live view, after the no-browser reason and before the Grid-has-no-VNC reason. The check reads the record's headless setting, so ran's live-view flag stays what the Grid said.

SET-25. headless=true sends --headless=new in goog:chromeOptions.args on Chrome and -headless in moz:firefoxOptions.args on Firefox, with source option. headless=false sends nothing.

SET-26. insecure always sends acceptInsecureCerts, true or false, on both browsers, so Firefox refuses a bad certificate as Chrome does. A browser opened insecure is not restored saved site data: when the workspace has any, the open's site_data.skipped says an insecure browser gets no saved site data, and nothing is deleted.

Capabilities

SET-27. What an open sends is built in one place, session_caps.build, from four layers, in this order: flow (what selenium-flow always sends), option (what a named setting produces), config (session.capabilities, the operator's) and raw (the call's capabilities). The config object is its own source, merged under the raw one at every open; it is not a lower layer of the stored raw setting, so a config change reaches the next open of a workspace that remembers a raw object. What is built is exactly what is sent: Selenium's own extra keys (pageLoadStrategy, and on Firefox moz:debuggerAddress) are not sent.

SET-28. Flow always sends unhandledPromptBehavior: ignore, se:downloadsEnabled: true and webSocketUrl: true, plus its own block entries: on Chrome the args --no-sandbox and --disable-dev-shm-usage and four prefs, on Firefox five prefs. Option sends browserName; browserVersion unless unset or latest; acceptInsecureCerts; and for record, se:recordVideo and, with a video name, se:videoName.

SET-29. Owned keys cannot be set by capabilities or session.capabilities. A raw key is a 400, a config key stops the server at load, and the message is <key> cannot be sent in capabilities: <what to use> (where is session.capabilities for config), several joined with ; :

Key Use instead
browserName browser=
browserVersion version=
acceptInsecureCerts insecure=true or insecure=false
se:recordVideo, se:videoName record=true
timeouts page_load_timeout= and script_timeout=
unhandledPromptBehavior, se:downloadsEnabled, webSocketUrl none: selenium-flow needs them

SET-30. Both vendor blocks are checked whatever browser opens, because stored capabilities survive a switch of browser. A block that is not an object, args that is not a list of strings and prefs that is not an object are each a 400 naming the path. A headless flag is refused in either block: an args entry that reads headless once leading dashes and any =value are stripped, in any case (--headless, --headless=new, -headless, -HEADLESS), and any moz:firefoxOptions.env.MOZ_HEADLESS. The message reads <block>.args <arg> cannot be sent in <where>: use headless=true or headless=false instead.

SET-31. A raw or config key that is not owned replaces the other layer's value, raw over config, and its source is the layer that won. The other browser's vendor block is sent untouched. sent lists every key with its value and sources in the order: option keys, config and raw keys, the browser's own block, flow keys.

SET-32. The browser's own vendor block (goog:chromeOptions or moz:firefoxOptions) is merged and its sources are every layer that fed it. args are listed flow, option, config, raw, with exact duplicates removed. prefs merge as one object: flow beats config and raw, and raw beats config. Any other key in the block comes from config, then raw.

SET-33. ignored lists <block>.prefs.<name> for each config or raw pref whose value differs from the one that won. Args are never ignored. The open's result carries ignored only when it is not empty.

SET-34. A stored raw key that a later release makes owned is refused, not dropped, on an explicit open that did not pass capabilities and on a reap's reopen alike. The message adds ; this workspace remembers it, so clear it with open_session(capabilities={}). The same suffix follows a refused headless flag.

SET-35. A headless flag in session.capabilities stops the server at load with the same sentence, because a config flag would be a default for headless, which has none.

SET-49. Both browsers open with their save-password prompt switched off by preferences. The prompt is a browser popup that takes the input focus and keeps it, so every later click and keystroke goes to the popup and nothing happens, with no error. On Chrome credentials_enable_service, profile.password_manager_enabled and profile.password_manager_leak_detection are false. On Firefox signon.rememberSignons is false. They are among the prefs of SET-28, so a raw or config pref of the same name loses to them and, when its value differs, is listed in ignored (SET-33).

What the Grid refuses

SET-36. The open sets no client timeout of its own, so it waits as long as the Grid's queue does. A request the queue gives up on (New session request timed out or Timed out creating session) is a 503 reading no Grid node took this browser before the Grid gave up waiting: it asked for <asked>. The Grid may have no node with these capabilities, or none free; see the troubleshooting reference.

SET-37. <asked> is browserName, browserVersion, then platformName and every key with a : outside goog:, moz:, ms:, safari: and se:, those being the keys the Grid matches on. A scalar is quoted as key=value, anything else as the key alone. A vendor block or proxy is never quoted.

SET-38. The Grid's own failures (Unable to find owning node for slot, Interrupted when creating the session, An error occurred creating the session, No capabilities found in session request payload, Client has gone away) stay the plain 503 with the Grid's words.

SET-39. Any other SessionNotCreatedException is a node refusing the browser. It is a 400 when the open sent raw keys or a version the caller owns, and a 503 when it sent neither. The message carries the node's reason with the Grid's host and build lines removed.

SET-40. A version is the caller's when it came from the call, from Sf-Version or ?version=, or from this workspace's memory (SET-17 keeps the source across a reap). A version from config alone is the operator's: it never makes the refusal a 400, and the 503 names session.version. The 400 says where the version came from: from this call's version=, from Sf-Version or ?version= or remembered by this workspace (version="latest" forgets it). Config capabilities never blame the caller. latest sends no version, so it is never blamed.

SET-41. A page whose certificate the browser does not trust, on the first page of an open or on navigate, is Untrusted, a 400 (ERR-17). The message never carries the browser's own text, which quotes the URL.

SET-42. A script run by execute_script, or an assertion script, that outlives the session's script timeout is ScriptTimedOut, a 400, on both browsers (ERR-17).

SET-43. A browser an open made is never left behind: anything that fails after the Grid created it (a hook, the window, the first page) quits it, and the failure is what propagates.

What a caller is told

SET-44. open_session's result has workspace, browser, version (the version that ran, or null), url, title, width, height (measured on the new browser), recording, capture, settings, and when they apply ignored, site_data and flows_here.

SET-45. The result's settings is what this browser opened with: browser, the measured width and height, a timeout when set, insecure, headless, record and capture only when true, version as asked (latest included) and capabilities when not empty. The Grid's session id and sent and ran are never in a caller's result.

SET-46. workspace://current (WS-43) shows the record's settings as stored, which keeps a flag passed false and the window as asked, and version as it ran beside browser. It shows no sources.

SET-47. The admin's workspace row carries insecure, headless, set_by (the source of each setting), asked_version, sent, ran, ended and grid_listed. grid_listed is false when the Grid's listing failed, and then a row's recording stands on its stored setting instead of turning off.

SET-48. open_session's description is the prompt a model reads: it presents the named options as one set, says each is remembered when passed and that an option left out comes from the server's and connection's defaults at each open, and presents raw capabilities last as the escape hatch.

Clone this wiki locally