kubed/selenium-flow repository overview

⁠🌊 Selenium Flow

One browser, many calls. Drive a real Chrome or Firefox on Selenium Grid⁠ from an agent over MCP — or from anything else over plain HTTP. Same actions, same server, one browser that stays exactly where you left it. 🧭

⁠The whole idea, in one breath

Open a browser once. It stays alive — same page, same cookies, same scroll position — while an agent works a task one call at a time, or an n8n workflow steps node to node. Nothing relaunches, nothing logs in twice.

   agent  ──── MCP  /mcp ─────▶  ┌───────────────┐        ┌───────────────┐
                                 │ selenium-flow │ ─────▶ │ Selenium Grid │ ──▶ 🌐
workflow  ──── HTTP /browser ──▶ └───────────────┘        └───────────────┘
                                  holds no browser          the browser
                                                            lives here

This server holds no browser. The browser lives on the Grid, and with WORKSPACE_STORE=redis the record naming it does too — so the server can restart or scale to zero without anyone losing a tab. With the default in-memory store, a restart forgets which browser was whose. 🪄

⁠🔀 Two surfaces, one implementation

Every action is a tool and an endpoint, one to one, and a test fails the build if that stops being true. They differ in one place: screenshot hands MCP an image block a vision model can see, and HTTP a base64 payload.

GET /health and GET /openapi.yaml need no credentials.

⁠🧰 Every action, both ways

Nineteen actions, each a tool and an endpoint with identical parameters — a request body is the tool's schema, with nothing added and nothing taken away.

Every parameter, return field and trap worth knowing is one page per action in the wiki⁠ — generated from the live tool schemas. The same schemas are served at GET /openapi.yaml.

⁠🦊 Chrome or Firefox

open_session(browser="firefox") and you are on Firefox; leave it out and you are on Chrome. Every other action behaves identically on both (plain W3C WebDriver), so only session creation differs.

⁠🧠 A workspace is not a browser

The workspace outlives the sessions it holds — a session is the live browser open in it, one at a time. When the Grid reaps an idle one, or an operator ends one, the workspace keeps the browser choice, the window and the page it was on — so recovery is one call with no arguments:

open_session()      # same browser, same window, back where you were

Workspaces expire on WORKSPACE_TTL, slid forward on every use; nothing else removes one. More in the wiki⁠.

⁠🧭 About that url parameter

click, write, press_key, extract, screenshot and execute_script all take an optional url, which is not an assertion: if the browser is elsewhere it goes there first, so you can jump straight to a page instead of clicking a path to it.

⁠🍪 Workspaces

Every workspace is named by whoever calls, on both surfaces. Say who you are and you get the browser that belongs to that name — there is no session id in the contract, so nothing to keep or pass.

The old ?session= and X-Session-Key are refused with a 400 naming the new spelling.

Sending both is a 400: two names is two ideas about who is calling. Naming nothing is a 400 too, with a message saying how — except on the flow library, which falls back to the shared global one that everyone reads and nobody writes.

open_session always comes first. Nothing opens a browser implicitly, because that is the only place its browser, window size and timeouts are chosen.

Call again with the same name — after a reconnect, a restart, a week later — and you are back on the same browser at the same page.

Browser lifetime is the Grid's (SE_NODE_SESSION_TIMEOUT, 300s here); how long a workspace is remembered is WORKSPACE_TTL, slid forward on every call. Nothing runs a cleanup loop.

⁠📍 Where am I?

workspace://current reports the workspace name, which browser it is running, the page it is on, whether a session is open at all, whether you are inside a frame, and the window size. Reading it never opens a browser.

Everything there is to read is a resource like this one, and a client whose model cannot read resources — VS Code Copilot, or anything declaring ?resources=off — gets two tools instead: list_resources and read_resource(uri).

⁠📖 It teaches you how to use it

The server ships an Agent Skill: the strategic half tool descriptions cannot hold — how to name a workspace, why extract beats screenshot by orders of magnitude, how to reach a page in one call, and what a timeout usually means.

SKILL.md is a thin index; each reference is its own resource, so an agent loads only what its task needs:

Those URIs are FastMCP's convention, served by its own SkillProvider, so list_skills and download_skill work here with no special casing.

A client that implements the MCP Skills extension also finds it through skills/list and skills/get, and can verify every file it reads.

A client that cannot read resources reads the same URIs with read_resource. MCP_SKILL=false turns the skill off.

⁠🔁 Flows — do it once, run it forever

Drive a form once, save the steps under a name, and every run after that is one call:

run_flow(name="sign-up", params={"email": "[email protected]"})

A step is just a tool call, validated against the live tool schemas when it is saved — so a flow that could not run is refused before it starts. It runs in whatever browser you already hold, which means the same flow checks Chrome and then Firefox without an edit. Each workspace keeps its own library, beside a shared one called global that every workspace can run and none can change. Set DATA_DIR to turn them on; workspaces live under DATA_DIR/workspaces/<name>/.

⁠🔐 Secrets — typed, never shown

Mount credentials as a directory per secret and a file per key — exactly how Kubernetes already mounts a Secret — and point SECRETS_DIRS at it. An agent sees the names and keys, never a value, and binds one where the value would go:

write(selector={"css": "#password"}, secret={"name": "nextcloud", "key": "password"})

The server types it; it never passes through the model, the transcript or a log. A secret can be pinned to the sites it may be used on, and is refused anywhere else.

⁠🗂 Files, Screenshots, Recordings and Downloads

Four sections, addressed by path, that never merge into one list:

keep_file(uri) moves a screenshot or recording into Files, or copies a download there before the browser ends it. upload_file(file=uri) puts a file from any of the four into a page's file input. No agent tool clears or deletes anything — that is an operator action in the Admin UI⁠ below.

Every entry carries a link to hand someone — signed and time-limited when the server has a token, a plain path when authentication is off — because an <img> tag cannot send an Authorization header. screenshot(save=false) opts out when a capture is not worth keeping.

⁠🎬 Recording

open_session(record=true) films the browser's whole life — from that call until the browser ends or the Grid reaps it — and the video appears under workspace://files/recordings (and in the admin page's Recordings row) shortly after. Like screenshots, they stay until kept into Files or cleared.

open_session(capture=true) keeps the page's console and network for workspace://console and workspace://network, and a call that caused a page error says so.

Selenium records; you deliver; selenium-flow files. Every docker-selenium node image from 4.45.0-20260606 contains the recorder and starts it for a session that asks with se:recordVideo. The Grid has no endpoint to download a recording, so how it reaches this server is yours to choose. The one rule:

Both sides need write access to that directory: the Grid's side writes, this server moves the finished file out once it has sat unchanged for RECORDING_SETTLE seconds, because a transport may still be finishing with it (rclone checks an upload after writing it, and uploads one that vanished again). Keep SE_NODE_MAX_SESSIONS=1 on recording nodes, or recordings share one screen.

• A shared volume. Mount the same directory at the nodes' /videos and at RECORDING_DIR here. Nothing else to configure.
• rclone, to anything. The recorder uploads each finished file with rclone: set SE_UPLOAD_DESTINATION_PREFIX and an RCLONE_CONFIG_<REMOTE>_* remote on the nodes — a WebDAV such as Nextcloud whose folder is the same storage as RECORDING_DIR, S3, SFTP. Leaving --inplace out of SE_UPLOAD_OPTS makes rclone write *.partial and rename, which this server waits for.
• A local folder for stdio or compose: bind-mount it into the Grid container at /videos. In docker-compose.yaml this is opt-in, because Docker creates a missing folder as root and this image runs as 65534: run mkdir -p data/recordings && chmod -R 777 data once, then uncomment DATA_DIR, RECORDING_ENABLED, both volumes and the Grid's SE_VIDEO_EVENT_DRIVEN=false and SE_VIDEO_RECORD_STANDALONE=true, which a standalone container may need to start its recorder (not yet verified). If a standalone image's built-in recorder does not start, docker-selenium's separate selenium/video sidecar, sharing /videos, does the same job (not yet verified).

A recording is matched to its session by the Grid's session id anywhere in its path below RECORDING_DIR (folders or file name), so any path and prefix the transport adds is fine.

What the recorder must be set to. Keep SE_VIDEO_FILE_NAME=auto (the default): a fixed name gives every session the same file, which cannot be matched. And keep either SE_VIDEO_FILE_NAME_SUFFIX=true (the default) or SE_VIDEO_SESSION_SUBFOLDER=true, so the Grid session id is in the path; with both off a custom se:videoName carries no id, the recording is made, and it is never matched. One that never arrives is given up on after RECORDING_WAIT seconds with a warning in the log.

⁠🖥 Admin UI

GET / — your workspaces, marked with the browser each is running. Open one for its Files tab — Downloads, Screenshots, Recordings and Files, each cleared the way that fits it — and its Flows tab. Click a file to view it in place; End quits a stale browser and gives its Grid slot back, rather than waiting out the Grid's idle timeout — it ends the session and keeps the workspace.

Workspaces, not Grid sessions: browsers somebody else put on the Grid are not listed. Nothing on the MCP surface lists workspaces at all — a client sees its own and nothing else. More in the wiki⁠.

The list pushes its own updates over Server-Sent Events — no refresh button, and no polling per tab: one loop serves every page.

There are no accounts: the sign-in box asks for the server's token, since anyone holding it can already drive every browser through the API. It is kept in sessionStorage, so it does not outlive the tab.

The Grid's own console is a second tab, framed same-origin. Put both behind one host — the Grid at /, this server under a path — and its live view works with no cross-origin exception.

⁠🧩 MCP Apps

Hosts implementing the MCP Apps extension⁠ — Claude, ChatGPT, VS Code, Goose — render a tool result as UI rather than JSON. show(uri) draws any resource the server serves: your workspace, its files, site data, flows, secrets and the skill.

The views are the app's own; the files grid, lightbox and browser marks are shared with the admin UI, not copied. Degradation is the point: one server, the client's capabilities pick the rendering.

Apps get a deny-by-default CSP with no network, so PUBLIC_BASE_URL is also what admits this server's images to the frame. MCP_APPS=false turns it off.

⁠⚙️ Configuration

Every setting can be set in a YAML config file, in the environment, or on the command line, and a later one wins: default < config < env < args. A setting's file path is its name: redis.host is REDIS_HOST and --redis-host.

# /etc/selenium-flow/config.yaml
grid:
  url: http://selenium-hub:4444
redis:
  host: redis.data
secrets:
  entries:
    nextcloud:
      allowed_urls: [https://nextcloud.example.com]
      keys:
        password: {env: NEXTCLOUD_PASSWORD}

Point at the file with --config-file or CONFIG_FILE. Prefer file: or env: for a secret's keys — value: writes the value into the config file itself.

Every setting, in all three spellings: the wiki's Configuration⁠ page.

⁠💾 The data directory

DATA_DIR turns on flows, kept files and recordings; unset, they are off.

$DATA_DIR/
├── workspaces/<name>/{flows,files,screenshots,recordings}
└── recordings/          # RECORDING_DIR's default: where the Grid's videos arrive

Upgrading: a :main build's $DATA_DIR/sessions/ moves itself to workspaces/ at the first boot; both present stops the boot until you merge them. Roll the upgrade out with Recreate (or scale to 0): an old pod still writing sessions/ makes the next boot stop on "both exist". With Redis, REDIS_PREFIX=selenium-flow:session: keeps the old records. From a released version (FLOW_DATA_DIR), workspaces sat at the top of the directory, and the server refuses to boot until they move — once:

cd "$DATA_DIR" && ls             # the old workspace folders, and recordings/ if any
mkdir workspaces && mv <each workspace folder> workspaces/

Leave recordings/ where it is, then set DATA_DIR in place of FLOW_DATA_DIR. workspaces and recordings are reserved names: an old workspace called either is refused at boot until you rename it (say workspaces-old) and move it into workspaces/.

⁠Session defaults cascade

The browser, the window size and the two timeouts resolve in order of increasing specificity:

server default (config: session.*)  <  client default (?width= / X-Window-Width)  <  open_session argument

A bad client default is ignored and logged; a bad session.* in the config, env or args stops the boot, and an explicit browser argument fails loudly.

⁠🔐 Auth

Setting AUTH_TOKEN turns on auth for both surfaces at once. Clients send it the usual way:

Authorization: Bearer <token>

The HTTP endpoints also accept the bare token as the Authorization value, for clients that can't express a scheme. /health is always open.

It is also the signing key for file links and the event stream, so rotating it revokes those too. In the cluster External Secrets generates it.

Behind an OIDC gateway, /mcp also takes your identity provider's JWT. Set these beside AUTH_TOKEN, and the server checks the signature, audience, expiry and role itself:

OIDC_ISSUER=https://auth.example.com/realms/example
OIDC_AUDIENCE=https://mcp.example.com
OIDC_JWKS_URI=https://auth.example.com/realms/example/protocol/openid-connect/certs
OIDC_ROLES=mcp

The admin UI can sign in with the same issuer, for a person holding an admin role — register a public client for it and add:

OIDC_CLIENT_ID=selenium-flow-admin
OIDC_ADMIN_ROLES=admin

The token keeps working beside both, and stays the admin's.

⁠🚀 Running it

docker compose up --build

That starts the server and a standalone Grid for it to drive, with auth off:

curl -X POST localhost:8000/browser \
  -H 'X-Workspace: demo' -H 'Content-Type: application/json' \
  -d '{"url":"https://example.com","width":1280,"height":800}'

Point an MCP client at http://localhost:8000/mcp, open localhost:8000 — and watch the browser work live at localhost:7900, the Grid's noVNC view. 👀

⁠🛠 Contributing

Setup, tests, how the OpenAPI spec is generated and how the embedded skill is packaged: CONTRIBUTING.md⁠. Design rules worth reading before changing behaviour: AGENTS.md⁠.

⁠🔗 References

• Model Context Protocol⁠ · MCP Apps⁠ · FastMCP⁠
• Selenium Grid⁠ · Selenium Python API⁠
• Docker Hub⁠

⁠📜 Licence

MIT. See LICENSE⁠.

Not affiliated with, endorsed by, or sponsored by the Selenium project. "Selenium" is a trademark of the Software Freedom Conservancy, used here only to identify the software this server drives.