Administration

Administration

The token, the admin UI, and the files a session leaves behind.

The token

Setting MCP_AUTH_TOKEN turns on authentication for both surfaces at once. Leave it unset and the server is open — correct for docker compose up, and the reason a real deployment always sets one.

It is not only a credential. The same value is the signing key for file links and the event stream, so rotating it revokes every link already handed out. That is deliberate: it means there is one secret to manage rather than three, and one action that invalidates everything.

Making one

Any long random string works. What matters is that it survives being pasted into a client config, so keep it alphanumeric:

openssl rand -hex 32

In Kubernetes, don't. Let External Secrets generate it so no value is ever authored, committed, or staged in a vault — see Deployment. To read the current value:

kubectl get secret selenium-flow-auth -n flow \
  -o jsonpath='{.data.MCP_AUTH_TOKEN}' | base64 -d

Using it

Authorization: Bearer <token>

Both surfaces accept that. The HTTP endpoints additionally accept the bare token as the whole header value, for clients that cannot express a scheme.

GET /health and GET /openapi.yaml are always open. A kubelet has no token, and a contract you must authenticate to read is needlessly awkward.

Rotating it

1. Replace the secret. In Kubernetes, delete it and let the generator remake it: kubectl delete secret selenium-flow-auth -n flow
2. kubectl rollout restart deploy/selenium-flow -n flow — envFrom does not reload, so the pod keeps the old value until it restarts.
3. Update every client. Anything holding the old token now gets a 401, and every signed file link stops working.

---

The admin UI

GET /admin — the browsers the Grid is running, what each has downloaded, and the Grid's own console framed as a second tab.

There are no accounts. The sign-in box asks for the server's token, because anyone holding it can already drive every browser through the API; a second identity system would only be one more thing to get wrong. It is kept in sessionStorage, so it does not outlive the tab you typed it into.

What the list tells you

These are flow sessions, not Grid sessions. The Grid is the superset — it runs browsers put there by anything at all — and those are deliberately not listed: showing them would present somebody else's work as though it were ours. The Grid console tab is there if you want to see the Grid itself.

A flow session is a caller and its context. It may or may not be holding a browser right now:

Row shows	Means
a name	keyed with ?session=<name> or X-Session-Key
mcp client	keyed on a negotiated transport id
stateless	a caller with nothing stable to key on, recorded under its browser
live	a browser is attached and the Grid still has it
idle	no browser attached — reaped, or ended here

An idle session is not broken. It kept the browser it was using and the page it was on, so its caller's next open_session picks all of that back up.

Sessions expire on SESSION_TTL, slid forward on every use — a day by default. One in daily use never goes; one abandoned yesterday is already gone. There is no delete button on purpose.

Each row is also marked with the browser it is running — 🟢 Chrome, 🦊 Firefox — read from the capabilities the Grid reports, so it is the browser actually running rather than the one that was asked for.

The list pushes its own updates over Server-Sent Events, so there is no refresh button. One poll loop on the server feeds every open page, rather than each tab polling on its own.

Ending a browser by hand

Click into a session and its toolbar carries End browser, beside Clear files. It quits the browser and gives its Grid slot back immediately, and is unavailable when the session is already idle.

The list rows carry no buttons on purpose: an action inside a card sits next to the status pill and makes that pill look clickable too.

It does not delete the session. The record stays, with its browser choice and last page, and the row goes idle. That is the difference that makes this safe to click: the caller loses the browser's live state — a login, a half-filled form — but not its place, and its next open_session carries on.

You do not have to click it at all. An abandoned browser expires on its own: the Grid reaps it after SE_NODE_SESSION_TIMEOUT seconds idle (300 by default), and where the browser nodes autoscale, the node then scales back to zero. The button is for not waiting out those minutes while a slot sits held — the Grid runs a handful of browsers in total, so a stale one is capacity somebody else needs.

The MCP surface has none of this

An MCP client gets open_session and end_browser, and can only ever touch its own session. Nothing there lists sessions, because a listing would hand any client somebody else's browser id — which is the whole credential for driving that browser. This page describes the admin surface: HTTP and UI, gated on the server token.

Endpoints behind it

Route	Auth	Returns
GET /admin	none — it is the sign-in form	the page
GET /admin/sessions	bearer	the list, plus a signed events_url
GET /admin/events	signature	the list again, whenever it changes
DELETE /admin/sessions/{key}	bearer	ends its browser; the session is kept
`GET	DELETE /admin/sessions/{key}/files`	bearer
GET /files/{session}/{name}	signature	the file itself

---

Session files

Everything a session downloads is kept by the Grid, in a per-session store on the node beside the browser. It is created with the session and deleted with it, so there is nothing to clean up and nothing accumulating on this server's disk.

Two kinds of file land there, and they are not distinguished — to you they are the same thing, files this browsing session produced:

• whatever the site served to a download: a click on Export CSV, a PDF, an installer
• whatever you kept: screenshot(save=true), save_pdf

This needs SE_NODE_ENABLE_MANAGED_DOWNLOADS=true on the Grid node. Without it the browser downloads somewhere nothing can reach.

Sharing one

A file is often wanted somewhere that cannot present a token: an <img> tag, a markdown image in a chat transcript, a link to a colleague. Browsers do not attach an Authorization header to an image request, so those URLs are authorised by signature instead:

/files/{session}/{name}?exp=1788931047&sig=f2235d5d072cea12…

The signature covers that exact path and that expiry, so a link grants one file for an hour rather than access to the API, and a recipient cannot extend their own link by editing the query. session_files and the admin UI both hand these out already signed; nothing needs to construct one.

Three ways this is normally used:

• an agent that cannot display an image returns the link, and a chat that renders markdown shows the picture
• the admin UI uses them as <img src> for thumbnails, and opens images and PDFs in a lightbox rather than a new tab
• you paste one to somebody who has no token at all

Rotating MCP_AUTH_TOKEN invalidates all of them at once.

Later

Files live and die with their session, which is right for a screenshot and wrong for anything you meant to keep. A WebDAV backend behind the same interface is the intended answer and is not built yet.