Skip to content

runtime

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

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.

Use cases

  • An operator restarts the pod and knows which workspaces, files, captures and live views survive.
  • An engineer adds an async tool 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.

Neighbours

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.

Starting

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:

  1. the Grid client (no request is sent);
  2. the workspace store (Redis is pinged here), then the pointer store on the same backend;
  3. the optional skill;
  4. the flow and file store over data.dir;
  5. the event bus, capture, the live view's page follower and the session monitor;
  6. control and the tunnels, the BiDi channels and the recording collector;
  7. the secrets catalogue and the workspaces object;
  8. the auth doors;
  9. the MCP app with its lifespan and the Tasks extension;
  10. the tools, resources, prompts, mirror tools, show, files tools, flow tools and secret routes;
  11. the middleware;
  12. 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).

The probes

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.

Stopping

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:

  1. Before Docket's worker stops, control releases every pending grant and every await_control waiter returns (PROT-20).
  2. The collector stops.
  3. The tunnels close with 1001 the server is stopping.
  4. The monitor closes every BiDi connection cleanly.
  5. The bus delivers what it queued and stops.
  6. 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.

What survives a restart

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

Concurrency

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_threadsafe and blocks for the result, with a bounded timeout, or hands it a callback with call_soon_threadsafe. Waiting from the loop's own thread would deadlock and raises.
  • The loop reaches a worker with anyio.to_thread.run_sync or run_in_threadpool for anything that blocks: a Grid request, a disk read, a store call, a catalogue read.
  • Code on the loop never blocks. An async tool 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.

Data

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).

Packaging

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:

  1. A Node stage builds the UI once on the build host.
  2. A Python 3.14 stage installs the runtime dependencies and the redis extra into a virtualenv at /opt/venv, installs the project, copies the UI into the package and removes pip.
  3. The runtime stage is Python 3.14 slim. It copies /opt/venv to the same path, checks at build that the server imports, and sets EXPOSE 8000, USER 65534 (numeric, so a kubelet can verify non-root) and ENTRYPOINT ["selenium-flow"], with no CMD.

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.

Limits

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

Browsers

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

Behind a gateway

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.

Clone this wiki locally