Repository navigation
runtime
What the process does from start to stop and what it keeps while it runs. This area holds the cross-cutting facts no single area owns: what is built in what order and what stops the boot, what the four probes track, how the server shuts down, what survives a restart, which code runs on which thread, where every byte of data lives, what ships in the wheel and the image, every cap in one table, and where Chrome and Firefox differ.
- An operator restarts the pod and knows which workspaces, files, captures and live views survive.
- An engineer adds an
asynctool and knows what it must not call, or a sync tool and knows what it costs. - A packager builds the wheel without the admin UI and the server still starts.
- An engineer raising a limit finds its value, config key and owning requirement in one place.
RUN-1. Each area owns the behaviour behind its row: config.md the settings and what a bad one does at start, workspaces-and-sessions.md the store, the monitor and the turn, workspace-files.md the folders and recordings, grid.md the Grid contract, protocol.md FastMCP, tasks and Docket, errors-and-logging.md log levels and failure wording.
RUN-2. selenium-flow (kubed.selenium_flow.main:main) loads the configuration, configures
logging, builds the server, logs one config= line and its warnings (CFG-35, CFG-36), and serves.
Logging is configured after a good load and before the build, so a build failure is logged.
RUN-3. The build runs in this order, each part existing for the ones after it:
- the Grid client (no request is sent);
- the workspace store (Redis is pinged here), then the pointer store on the same backend;
- the optional skill;
- the flow and file store over
data.dir; - the event bus, capture, the live view's page follower and the session monitor;
- control and the tunnels, the BiDi channels and the recording collector;
- the secrets catalogue and the workspaces object;
- the auth doors;
- the MCP app with its lifespan and the Tasks extension;
- the tools, resources, prompts, mirror tools,
show, files tools, flow tools and secret routes; - the middleware;
- the HTTP routes and the admin routes.
RUN-4. The lifespan starts, in order, control, the bus, the monitor and the collector. Nothing is listening for a call before it has run.
RUN-5. These stop the boot, with no listener: a ConfigError from load or from the build, which
exits 1 with selenium-flow: <message> on stderr (CFG-32, CFG-33, FILE-51, WS-46); and Redis named
and unreachable, or its package missing, which ends with a traceback (CFG-34). A missing or
unloadable packaged skill, a missing admin UI build (the page answers a placeholder) and an
unreachable Grid do not stop it.
RUN-6. Over stdio the same build and lifespan run with no HTTP listener, no probes and no
admin routes, and the caller's workspace is stdio (WS-1).
RUN-7. The four routes answer at the root and under route_prefix, open to everyone (AUTH-5,
SURF-34). What each tracks:
| Route | Tracks | Answers |
|---|---|---|
/health |
nothing: the process answers | {"status": "ok"} |
/started |
nothing: the process answers, which is only after the build | {"status": "started"} |
/ready |
the Grid: value.ready of GET /status and the session count of POST /graphql (GRID-13), cached for 2 s, asked off the event loop |
200, or 503 degraded with the credential-free Grid address and error |
/info |
nothing: the process's identity |
name, version, mount, mcp, grid without credentials, workspaces (the store's kind) |
/ready does not ask the store, the data directory or the inbox.
RUN-8. SIGTERM and SIGINT are uvicorn's, run by FastMCP. It stops accepting connections and runs the lifespan's exit after open connections have had a short grace (2 s in FastMCP's configuration). The admin event stream and the capture tail end themselves within 1 s of it.
RUN-9. The exit runs in this order:
- Before Docket's worker stops, control releases every pending grant and every
await_controlwaiter returns (PROT-20). - The collector stops.
- The tunnels close with
1001 the server is stopping. - The monitor closes every BiDi connection cleanly.
- The bus delivers what it queued and stops.
- The secret scrubber stops its threads.
RUN-10. The exit waits for:
- a recording being filed: a move in progress finishes and marks its note;
- note writes in flight;
- the closing handshake of each BiDi connection;
- what the bus had queued.
It does not wait for a call running on a worker thread beyond uvicorn's grace, a Grid command in flight, or the live viewers. No browser is quit: every browser stays on the Grid until its caller, the admin or the Grid's reaper ends it. Nothing is flushed to the store, because every write is already durable.
RUN-11. A restart keeps what is on a disk or in Redis and loses the rest:
| What | Memory store | Redis store |
|---|---|---|
| Workspace records: settings, page, history, site data, saved reopen notice | lost | kept, for workspace.ttl after the last write |
| Browsers on the Grid | alive, but nothing names them until the Grid reaps them | alive; the next call binds to its workspace's browser |
| Pointer positions | lost | kept |
Flows, kept files, screenshots, recordings, recording notes under data.dir
|
kept | kept |
| Signed links | valid until their exp while the token is unchanged |
same |
| Keep-alive pings | none: no record names a browser to keep | resume at the workspace's next call (WS-36) |
| A recording still owed | rebuilt from its note (FILE-55) | same |
| MCP transport sessions, background tasks, capture buffers, held BiDi connections, live tunnels, control episodes, turns, monitor watches, the secret scrub's origins and forms, every cache | lost | lost |
RUN-12. One event loop, the one uvicorn runs, and a pool of worker threads. Where each part runs:
| Part | Runs on |
|---|---|
| The four probes, the admin event stream, the capture tail, the live view's sockets, the admin broadcast | the loop |
The async tools (await_control, run_flow, save_flow, show and the two mirror tools) and the async routes |
the loop, handing every blocking step to a worker thread |
| The MCP middleware | the loop |
| The event bus's fan-out and every subscriber's handler | the loop |
| The session monitor's task, its listing and ping timers | the loop; each GET /status and each ping on a worker thread |
| Every BiDi connection: the reader, each subscriber's drain task | the loop |
| Capture's buffers, filled from BiDi events | the loop; reads from worker threads |
| Control's grant poll (every 0.1 s), the tunnels, the page follower | the loop |
| The recording collector's task | the loop; its disk work on worker threads |
| Every sync tool (the browser actions) and the body of every action route | a worker thread |
Workspaces, the actions, the Grid client, the stores, file I/O, flows |
the calling worker thread |
| The scrub of a resource read | a worker thread |
| Secret catalogue reads for the scrub | the secret-scope pool: 4 threads |
RUN-13. FastMCP's sync tools and Starlette's routes share anyio's default limiter: 40 worker threads, not raised (WS-58). The Grid's pools are sized to it (GRID-6). The scrubber's pool is the only private pool. A private event loop thread is started for a BiDi channel only when no loop is running at all (a test or a script).
RUN-14. The locks, and what each guards:
| Lock | Guards |
|---|---|
A session's turn (locks.driving) |
One call at a time on a browser (WS-39) |
A memory-store key's lock; Redis WATCH
|
A compare-and-set of one record (WS-10) |
| The scrubber's lock | Its per-workspace entries and builds in flight; never held while the catalogue, capture or a callback is called |
| The origin tracker's lock | A workspace's current origin |
| Capture's lock | Every buffer, held session and pending queue; nothing slow runs under it |
| The monitor's two locks | The ended-session memory and the in-flight call counts |
| The flow store's hints lock; the parse cache's condition | The hint cache; the parsed-document cache (FLOW-54) |
| The collector's notes lock; each tunnel's output lock (asyncio locks on the loop) | Note reads against sweeps; a tunnel's writes to the viewer |
RUN-15. The rule for crossing between them:
- A worker thread reaches the loop with
run_coroutine_threadsafeand blocks for the result, with a bounded timeout, or hands it a callback withcall_soon_threadsafe. Waiting from the loop's own thread would deadlock and raises. - The loop reaches a worker with
anyio.to_thread.run_syncorrun_in_threadpoolfor anything that blocks: a Grid request, a disk read, a store call, a catalogue read. - Code on the loop never blocks. An
asynctool or route calls no Grid client method and no store method directly. - A bus handler runs on the loop, must not block, and answers with a post, not a wait (WS-29).
- A threading lock is never held across an await, and none is held while calling code that takes another.
- A sync tool that drives a browser holds a worker thread for its whole turn, queueing included.
RUN-16. Everything on disk. The paths under <data> and recording.dir exist only when
data.dir is set, and no folder has an expiry or a cap (FILE-5).
| Path | Holds | Owner |
|---|---|---|
the config file; each secrets.dirs entry; live.password_file
|
read-only inputs: YAML; a directory per secret with one file per key; the Grid's VNC password | CFG-16, SEC-3, LIVE-6 |
/tmp/selenium-flow-* |
an upload's staging copy, removed after the call | FILE-21 |
<data>/workspaces/<workspace>/flows/<name>.yaml |
a saved flow, UTF-8 YAML; the shared library is workspace global
|
FLOW-13 |
<data>/workspaces/<workspace>/files/<name> |
Files: a print, a kept file | FILE-4 |
<data>/workspaces/<workspace>/screenshots/<name> |
a PNG | FILE-16 |
<data>/workspaces/<workspace>/recordings/rec-YYYYMMDD-HHMM.mp4 |
a filed recording | FILE-59 |
<data>/workspaces/<workspace>/recordings/.pending/<gridId>.json |
a note: opened, ended, browser, filed or dropped
|
FILE-55 |
recording.dir, default <data>/recordings
|
the inbox the operator's transport fills; the server files from it and never cleans it | FILE-49 |
RUN-17. A flow document is written to a hidden temporary file beside its target and renamed over it, so a reader sees the old document or the new one. A file the server makes is created exclusive, and takes the next free name (FILE-9). A listing skips names starting with a dot, links and anything that is not a regular file (FILE-11).
RUN-18. Everything in Redis, and nothing else is written there:
| Key | Holds | Expiry | Owner |
|---|---|---|---|
<redis.prefix><workspace> (default prefix selenium-flow:workspace:) |
the workspace record, one JSON object |
workspace.ttl from each write |
WS-7 to WS-11 |
<redis.prefix>pointer:<Grid session id> |
the pointer's last position, a JSON [x, y]
|
workspace.ttl |
ACT-24 |
Listing the records skips the pointer: names (WS-10). The database is redis.db, default 0.
RUN-19. What is neither on disk nor in Redis is process memory, gone at a restart, and listed in the last row of RUN-11. The owners: capture buffers and held connections (CAP-32), control episodes (LIVE-14), the secrets catalogue's listing cache (SEC-8) and the parsed flow cache (FLOW-54).
RUN-20. The distribution is kubed-selenium-flow, versioned from git tags by setuptools_scm
(/info reports it), for Python 3.11 to 3.14 and MIT licensed. Its one console script is
selenium-flow, kubed.selenium_flow.main:main. It listens on 0.0.0.0:8000 over http unless
configured (CFG-37).
RUN-21. The optional extras are redis (needed only for workspace.store: redis), build,
profile, test and bench. The runtime dependencies are the behavioural contract: FastMCP 4
with its tasks extra and mcp 2 (see protocol.md), Selenium 4, websockets,
watchfiles (the recording inbox), cryptography (VNC's DES), cachetools, pyyaml,
python-multipart, sse-starlette, pydantic-settings and requests.
RUN-22. The wheel holds the kubed.selenium_flow packages and three trees that are not Python:
the page JavaScript, js/*.js in the checkout, installed as kubed/selenium_flow/core/js and read
by name; plugin/ in the checkout, installed whole, .claude-plugin/plugin.json included, as
kubed/selenium_flow/mcp/plugin; and the built admin UI, kubed/selenium_flow/http/static/*. The
UI is built from ui/ by npm run build, which writes to that folder (gitignored). A wheel built
without it installs and runs, and the UI's URL answers a placeholder.
RUN-23. The image has three stages:
- A Node stage builds the UI once on the build host.
- A Python 3.14 stage installs the runtime dependencies and the
redisextra into a virtualenv at/opt/venv, installs the project, copies the UI into the package and removespip. - The runtime stage is Python 3.14 slim. It copies
/opt/venvto the same path, checks at build that the server imports, and setsEXPOSE 8000,USER 65534(numeric, so a kubelet can verify non-root) andENTRYPOINT ["selenium-flow"], with noCMD.
No transport, host or port is baked into the environment, so a config file's value is not
shadowed by an env var. The image holds no browser and is built for linux/amd64 and
linux/arm64.
RUN-24. The image runs unprivileged and may run with a read-only root, so /tmp must be
writable for uploads, and data.dir and recording.dir must be writable by uid 65534 when set.
The start checks that recording.dir is readable, writable and searchable, and that data.dir
can be read (CFG-33); a data.dir the process cannot write fails at its first write.
RUN-25. Every cap, timeout and size bound in the server, with the requirement that owns it. A value with a config key is the key's default. A cap written in two areas is listed once, under its owner.
| Limit | Value | Config key | Owner |
|---|---|---|---|
| Worker threads for sync tools and routes | 40 | none | WS-58 |
| Scrub catalogue pool; wait for a read | 4 threads; 10 s | none | RUN-12; SEC-41 |
| Grid pools; plain request; idle-timeout read and ping | 40 each; 30 s; 5 s | none | GRID-6, GRID-14 |
| BiDi socket: open, reply, ping, frame | 5 s, 5 s, 20 s, 16 MiB | none | GRID-2, GRID-6 |
| BiDi subscriber queue | 1000 events, 32 MiB | none | CAP-17 |
| Monitor attach | 15 s | none | CAP-6 |
| Workspace record lifetime | 86400 s | workspace.ttl |
WS-9 |
| Redis update retries | 10 | none | WS-10 |
| Bus subscriber queue; ended-session memory | 1000; 4,096 ids | none | WS-29; WS-27 |
| Monitor listing tick; default node window | 30 s; 300 s | none | WS-31; WS-21 |
| Keep-alive window | 900 s, 0 to 3600 | session.keep_alive |
WS-35 |
| Keep-alive ping interval |
max(60, min(0.8 t, t - 60)); 240 s |
none | WS-37 |
| History | 100 origins | none | SITE-43 |
| Site data snapshot | 1,000,000 bytes | none | SITE-8 |
| Capture buffer | 1000 console rows, 1000 requests, 256 workspaces | none | CAP-33, CAP-35 |
| Capture lifetime | 10800 s, at least 60 | capture.ttl |
CAP-36 |
| Capture pending while secrets load | 200 events a context, 32 MiB, 10 s | none | CAP-60 |
| Request headers kept | 32, 16,384 bytes; names 256, values 4096 | none | CAP-65 |
| Network body: refused unasked; cut to | 8,000,000 bytes; 100,000 bytes | none | CAP-70; CAP-73 |
| Console text cut to | 4096 characters | none | CAP-19 |
| HTTP body: JSON; multipart upload | 1 MiB; 64 MiB | none | SURF-35 |
show result |
100,000 characters | none | SURF-30 |
| Wait for an element; for a dialog | 30 s; 10 s | the wait_timeout argument |
ACT-8 |
| Wait for a keystroke's navigation; for a title | 2 s; 1 s | none | ACT-13; ACT-14 |
| Pointer glide | 6 to 40 steps | none | ACT-23 |
| Pointer position lifetime | workspace.ttl |
none | ACT-24 |
| Paste | 10,000 characters | none | LIVE-37 |
| Live view: presence; grace; handshakes; client message | 10 s; 30 s, at least 15; 15 s; 1 MiB | live.grace |
LIVE-12; LIVE-8; LIVE-10 |
await_control blocking cap |
90 s, at least 30 | live.await_cap |
LIVE-28 |
| Progress heartbeat | 15 s | none | LIVE-34 |
| Control grant poll; pages followed for | 0.1 s; 15 s | none | LIVE-18 |
| File link lifetime; expiry step | 3600 s, at least 60; 600 s | link_ttl |
AUTH-24 |
JWT nbf leeway; JWKS refetch floor |
60 s; 60 s | none | AUTH-11; AUTH-14 |
| Admin list: recompute; fallback poll; stream keepalive | 2 s; 30 s; 20 s | none | UI-34, UI-35 |
| File name | 1 to 255 characters | none | FILE-10 |
| Flow document; flow name; run; flows named in a result | 1 MiB; 64 characters; 120 s; 10 | none | FLOW-4; FLOW-4; FLOW-33; FLOW-25 |
| Parsed-flow cache | 4 MiB of YAML | none | FLOW-54 |
| Recording: wait; poll; settle; idle filing | 600 s, at least 30; 1000 ms, at least 200; 10 s; 60 s |
recording.wait, .poll, .settle
|
FILE-50; FILE-58 |
| Secrets catalogue cache | 30 s | none | SEC-8 |
| Skill name; description | 64; 1024 characters | none | PLG-10 |
RUN-26. Every place the code branches on the browser, with the requirement that owns it.
Behaviour not listed is the same on both. tests/test_browser_choice.py is the one test module
that runs the cases on both.
| Where | Chrome | Firefox | Owner |
|---|---|---|---|
| Headless flag |
--headless=new in goog:chromeOptions.args
|
-headless in moz:firefoxOptions.args
|
SET-25 |
| Vendor block the server always sends | args --no-sandbox, --disable-dev-shm-usage; four prefs |
five prefs: the download folder (two), no ask for download types, PDF viewer off, no password manager | SET-28, SET-49 |
| Certificates |
acceptInsecureCerts sent explicitly |
the same, because Selenium's Firefox default accepts all | SET-26 |
| Options class of an open | Chrome's | Firefox's, so Selenium picks its connection | GRID-7 |
| Download scratch names |
.crdownload, a hidden .com.google.Chrome.*
|
.part |
FILE-7 |
| Unresolved host | net::ERR_NAME_NOT_RESOLVED |
the dnsNotFound error page, whose text quotes the URL |
ACT-18 |
| Script timeout | the text script timeout
|
Timed out after N ms; the server keys on the command, not the text |
SET-42 |
| Node or page crash |
session deleted because of page crash, tab crashed
|
only the hub's Unable to execute request for an existing session
|
GRID-15 |
| A character outside the BMP | ChromeDriver's refusal is matched and said | no refusal is matched | LIVE-38 |
| Navigation after Enter | pre-submit page read 2 of 6 times | 6 of 6; one settle for both | ACT-13 |
| Console replay on a new subscriber | the last 100 entries a context, aligned | none | CAP-14 |
| Request timing clock |
timeOrigin is the epoch, timings relative |
timeOrigin 0, timings epoch; one formula |
CAP-24 |
| A body larger than the socket | one frame past 16 MiB closes the socket | an event fans out to every socket, so a too-large frame may not be the reply | CAP-71 |
SameSite=None without Secure
|
refused by the browser, so restored as lax
|
the same conversion is applied | SITE-30 |
| HTML5 drag and drop | completed by the drag | not completed | none: the drag tool description only |
| MHTML print | exists, never offered | none | FILE-18 |
RUN-27. The server has no gateway-specific behaviour, and being reached through one is a
deployment choice. It reads the workspace from Sf-Workspace, X-Workspace or ?workspace=
whoever set them (WS-1), verifies a JWT a gateway forwards (AUTH-11), reads no X-Forwarded-*
header, builds links from public_base_url and route_prefix, and registers no
protected-resource metadata route, which is the gateway's or the issuer's to serve.
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