Repository navigation
Specification
What the server does, one area per file. Each requirement is numbered, says one thing, and is true of the code unless it is tagged (proposed). An agent that reads every file here can rebuild the server: the requirements and use cases are in the area files, and the glossary and architecture are below.
The spec holds the present only. Why a requirement is the way it is, and what it replaced, is in the dated designs and plans in plans/, each of which opens with a History header naming the requirement ids that hold it now. How to use a feature, in plain English, is on the wiki's hand-written pages, which link here for the rules. Setting up the repo, running the tests and shipping are in CONTRIBUTING.md.
| Area | IDs | Covers |
|---|---|---|
| Workspaces and sessions | WS | Naming a workspace, the record and its store, opening and ending a browser, reaps and reopens, the session monitor, the keep-alive, one call at a time, workspace:// and session://
|
| Session settings | SET |
open_session's options, where each value comes from, what a workspace remembers, raw capabilities, headless |
| Auth and roles | AUTH | The server token, OIDC on /mcp, the admin UI's sign-in, principals, signed links |
| Surfaces | SURF | The capability table, request headers, MCP tools and resources, the HTTP routes and OpenAPI document, show
|
| Live view and control | LIVE | Watching a browser over VNC, a person taking control, refusals, await_control
|
| Browser actions | ACT | What each action does: the recipe, selectors and waits, clicks and what received them, the pointer, keys, url=
|
| Saved flows | FLOW | The flow document, parameters, running one, sites and paths, flows_here
|
| Secrets and scope | SEC | The catalogue, the leash, binding a secret to a field, the scrub of every result and resource |
| Site data | SITE | Saving and restoring cookies and storage, the history, the spare tab |
| Capture | CAP | Console and network capture over BiDi, masking, the capture resources, a call's hint |
| Workspace files | FILE | Downloads, screenshots, prints, kept files, recordings, file addresses and links |
| Admin UI | UI | The admin page and its API, the tabs, the event stream, the MCP App shell |
| Config | CFG | Every setting, its three spellings, precedence, validation, the Settings tab |
| Plugin | PLG | The plugin/ folder: the embedded skill, the Skills extension, prompts, agents and the agents extension |
| Protocol | PROT | The two generations of MCP, the FastMCP stack, tasks, tool annotations, the instructions, the MCP App |
| Errors and logging | ERR | What each failure means, its status and wording, what is logged at which level and what never is |
| Grid | GRID | The contract with Selenium Grid: endpoints, socket addresses, binding to a session, timeouts, failures, the reaper, what is assumed |
| Runtime | RUN | Startup and shutdown, the probes, what survives a restart, the concurrency map, data on disk and in Redis, packaging, every limit, Chrome and Firefox |
Work not built yet is in a ## Proposed: section at the end of an area file: several sessions in a
workspace in WS, SURF, ACT, LIVE, FLOW, CAP and UI, and ownership and roles in AUTH and SURF.
An area file avoids the names of the wiki's top-level pages. A GitHub wiki addresses a page by its
basename, ignoring case and folder, so specs/secrets.md would answer to the same address as
Secrets.md.
- An id is the area's prefix and a number:
WS-12. Numbers count up within an area and are never reused. A removed requirement leaves a gap. - A requirement that is not built yet is written like the others and tagged (proposed). The tag comes off in the pull request that builds it. A proposed requirement that replaces a built one names it.
- A behaviour change edits its area file in the same pull request.
- Each rule has one owner, the area whose subject it is. Another area that needs it links the id instead of restating it, and a requirement reduced to a pointer keeps its id.
- Requirements cite each other by id, and code by symbol name (
Workspaces.act), never by line number. - Statements only: present tense, no dates, issue numbers or history. The repository is public, so
no hostnames or personal names. The maintainer is Dr K, and examples use
example.com.
Each word below means one thing, here and in the code. The area named at a term owns its rules.
- Workspace. The box a caller names, with
?workspace=or theSf-Workspaceheader. It holds flows, files, site data, history, capture and the settings it opens browsers with. It is never deleted: it expiresworkspace.ttlseconds after its last use (workspaces-and-sessions.md). - Session. The live browser open in a workspace, at most one at a time, started by
open_sessionand ended byend_browser, the admin's End or the Grid's reaper. It is the Grid's WebDriver session, whose id issession_id. An idle workspace has no session. Where the Grid's own session or the MCP transport session is meant, the text says so. - Record. What the store keeps per workspace: the
session_idwhen a browser is open, the browser asked for, the settings a caller passed and the page it was on. It never holds a browser (WS-7). - Grid, node. Selenium Grid owns every browser. A node runs browsers, films them and serves their VNC (grid.md).
- Caller. One request's who and which: the workspace name (read once, at the edge, from
?workspace=orSf-Workspace, orstdio), how it was named, and the principal, if any. Two callers with one principal can name two workspaces. - Principal, door. A principal is who a verified credential says the caller is:
admin(the server token) oroidc(a JWT from the configured issuer). A door decides which credentials a route accepts (auth-and-roles.md). - Admin, operator. Admin is an access: the principal
admin, or an admin-UI sign-in holding one ofoidc.admin_roles. An admin sees every workspace. The operator is the person who deploys and configures the server, its Grid and the transport that delivers recordings. The operator is a role in prose and never a credential, and the two words are not interchangeable. - Surface. How a call reaches an action:
mcp(a tool on/mcp),http(a route, mostly under/browser) orflow(a step of a running flow) (surfaces.md). - Capability. A row of
core/capabilities.py: one browser action with its tool name, route, annotations and response schema. Every action is a tool and an endpoint from one row. It is unrelated to WebDriver capabilities, thecapabilitiesobjectopen_sessionsends to the Grid. - Action, recipe. An action is a method of
core.actions.Actions. The recipe (core.recipe.Recipe.run) is the road every action takes: check the arguments, reattach to the browser, go tourlif one was named, wait for the element, act, report the page (browser-actions.md). - Selector. How an action names an element:
{"xpath": ...}or{"css": ...}, one of the two. - Flow, library. A flow is a saved YAML document of steps, each a tool call, plus the parameters a
run takes.
run_flowruns every step server-side in one call. A workspace's library is theflows/folder of its directory. The sharedgloballibrary is read by every workspace and written only by the admin (saved-flows.md). - Place,
flows_here. A flow'ssitesandpathssay where it applies. When a call leaves the browser on a page, its result'sflows_herenames the flows that apply there. - Site data, history. Site data is the cookies, localStorage and sessionStorage a workspace keeps
for the sites it used, saved by
save_site_dataand restored before a new browser's first page. History is the pages its browsers reached, kept with it (site-data.md). - Secret, leash, scrub, marker. A secret is a directory of files, one per key, or an entry in the
config file. Its leash,
allowed_urls, is the origins it may be typed on. An agent types one withwrite(secret={"name": ..., "key": ...})and never sees a value. The scrub checks every result, error and resource for the values in scope and replaces a find with the marker[secret:<name>/<key>](secrets-and-scope.md). - Capture. The console and network traffic of a browser opened with
capture=true, masked and kept per workspace forcapture.ttlseconds (capture.md). - Recording. The video of a browser opened with
record=true. The Grid films it, the operator's transport drops the file in the inbox (recording.dir), and the collector files it into the workspace. - Files. Lowercase
filesis a workspace's whole set, in four sections: Downloads (the browser's, on the Grid), Screenshots, Recordings and Files. Capitalised,Filesis the one section for what was kept on purpose withkeep_fileorprint.workspace://fileslists that section with the counts of the two folders and never Downloads (FILE-28). A signed link opens one file without a header (workspace-files.md). - Live view, control. The live view is the admin UI's Live tab: the browser's screen over the
node's VNC, proxied by this server and drawn with noVNC. Control is a person in the live view
taking the browser: requested, granted once the calls ahead have finished, then handed back.
While it is held, calls that would change the browser are refused, and
await_controlwaits for the hand-back (live-view-and-control.md). - Skill, prompt, agent. What
plugin/ships and the server serves: the skill atskill://selenium-flow/SKILL.md, prompts a person picks, and agent definitions through the agents extension (plugin.md). - MCP App,
show.show(uri)draws one resource inside a client that can show UI, using the app shell built fromui/(protocol.md). - Mirror.
list_resourcesandread_resource, two tools that read resources for a client that cannot. - Reap, reopen. The Grid ends a browser idle for its node's session timeout. The next call reopens
one with the stored settings at the last page, restores site data, and says so in the result's
reopened(WS-19 to WS-22). - Keep-alive. The monitor pings a browser for
session.keep_aliveseconds after its last call, so a pause between calls does not lose it (WS-35 to WS-38). - Monitor, bus, watch, reason. The session monitor announces
session.openedandsession.endedon an in-process bus. A watch is its record of one session it owes something on, and a reason is one thing owed:recording,capture,controlorkeepalive. A reason that names BiDi events holds a connection, and the others never do (WS-26 to WS-33). - Turn, hold. A turn is the right to drive one browser, one call at a time per session (WS-39). Hold has three uses and is never bare: a turn is held by the call driving a browser, a BiDi connection is held for a reason, and control is held by a person.
- Notice, note, hint. Three kinds of sentence beside an answer. A notice is about the workspace and
said once: the reopen notice, carried as
reopened(WS-22), and the control notice on MCP results while a person holds the browser or has just handed it back. A note is added to a failure's text after its first line, in a fixed order (ERR-16); an open's result also has anotefield when a concurrent open bound first (WS-14). A hint says where to look next and is never the action's answer: thepagehint of capture, the entries offlows_here, a failed run'shint, and thehintof a page state while a dialog blocks the page.
One Python package, kubed/selenium_flow, served by FastMCP over stdio or HTTP. It holds no
browser: each browser lives on the Grid, and a workspace's name leads back to it. It runs as one
replica, because the MCP transport session lives in its memory, as do each browser's turn, the
monitor's watches and bus, capture buffers, live-view tunnels, control episodes and background
tasks. A second replica would let two calls drive one browser and would watch nothing the first
opened. runtime.md has the startup order, the probes, shutdown and what survives a
restart (RUN-2 to RUN-11), what runs on the event loop and what on worker threads (RUN-12 to
RUN-15), and where every piece of data lives (RUN-16 to RUN-19). grid.md has
everything the server says to the Grid.
| Package | Responsible for |
|---|---|
server.py, main.py, config.py
|
Loading the settings and wiring every part below into one FastMCP app |
core/ |
The browser actions (actions.py), the recipe, the Grid client (browser.py), the capability table, element probes, the pointer, keys and the page JavaScript in js/
|
workspace/ |
Which browser a caller means (workspaces.py), the record store, session settings, the per-session turn, the call bracket (calls.py), the current origin and the secret scrub |
mcp/ |
The MCP surface: tools, resources, the mirror, prompts, the skill and its extension, agents, show, completions, progress and long waits, and the middleware for failures, control notices and scrubbed resources |
http/ |
The HTTP surface's shared parts: auth and doors, the one request answer, files and signed links; http/admin/ is the admin UI's page and API |
routes.py, spec/
|
The HTTP routes for every capability and the OpenAPI document built from the same table |
flows/ |
Flow documents, their store (which also holds the workspace's files), places, parameters, the run and its step loop, and the run's redaction |
monitor/ |
The session monitor and its event bus |
bidi/ |
The one WebDriver BiDi client: a connection per browser on an event loop, and the channel threads drive it through |
capture/ |
Capture's buffers, masking, Chrome's replay alignment and the views readers get |
site_data/ |
The site data snapshot, its BiDi transfer and the spare tab |
live/ |
The VNC tunnels, the RFB gate, control, the pages a person reaches, and the audit line |
recordings/ |
The collector that files each finished video from the inbox |
secrets.py, binding.py, redaction.py
|
The secret catalogue, the rule for binding a secret to a field, and every spelling of a value with the scanner that finds it |
names.py, urls.py, errors.py, faults.py, principal.py
|
Naming rules, URL and origin rules, what a failure means as a status, the package's own exceptions and messages, and the principal |
bidi/, capture/, live/, recordings/ and redaction.py import no Selenium and no protocol
layer; tests/test_boundaries.py holds each layer to its imports.
- A client sends
tools/callto/mcp. The/mcpdoor (http/auth.py) has already accepted the token or a JWT and attached the principal. - Middleware wraps the call, outermost first. It carries the caller's workspace to a background task's worker, adds the control notice while a person has the browser, and turns an exception into the one line a caller reads and the line the log writes. A resource read is scrubbed inside that last wrapper. Other middleware shapes what a client is shown at listing and handshake (surfaces.md, protocol.md).
- The tool's declaration (
mcp/tools.py) gives its schema and description, and its body comes from its capability row. It callsWorkspaces.actwith the caller. Awritewith a secret takes the bound write (secrets.perform_write), which follows the same steps from here. -
Workspaces.actresolves the record to a live Grid session, reopening a browser the Grid ended (WS-19 to WS-22). - It takes the browser's turn, notes the origin the call is about to reach, and begins the call. Beginning refuses it with a 409 while a person holds the browser, and asks the monitor to keep the session alive.
- The capability's action runs the recipe against the Grid (
core/browser.py). - The call ends: the monitor is told,
call.finishedis published and, with capture on, the result gets itspagehint. The scrubber then replaces any secret value in scope with its marker. - Back in
Workspaces.act, the record is touched with the page reached,flows_hereandreopenedare added, and site data is saved when the call asked for it. The result returns through the middleware to the client.
An HTTP call takes the same road from step 3: routes.py mounts the same row, http/answer.py
reads the body and maps a failure to its status (errors.status_for), and Workspaces.act runs
with surface="http". A flow step runs inside run_flow's own call, through flows/engine.py,
with surface="flow".
The action pages are generated from the server's tool schemas, so they describe the version that shipped.
selenium-flow · MIT
Start here
Guides
Lifecycle
Going places
Doing things
Getting things out
Site data
Console and network