Skip to content

admin ui

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

Admin UI

The admin page is how a person watches and tidies what agents do. It lists the workspaces, opens one, and shows its browser, files, flows, site data, history, capture and live screen. It is a Svelte 5 app under ui/, built into one script and one stylesheet that the server inlines into a page it serves at its own root. This file holds how the page is built and served, how it signs in, how it stays current, the conventions every tab follows, and the design it is drawn from. What each tab's routes do is in the area files named below.

Use cases

  • A person opens the server's URL, signs in with the token or the issuer, and sees every workspace with its browser state.
  • A person opens a workspace, watches its browser, takes a screenshot out of Files, ends the browser, or edits a saved flow.
  • A person leaves the page open and sees a browser appear, a file land or a recording finish without reloading.

Neighbours

UI-1. The sign-in checks and the admin door are in auth-and-roles.md. The routes behind each tab are in:

The tool that draws a resource in the MCP App is in surfaces.md. This file does not restate them.

How it is built

UI-2. The source is ui/: Svelte 5, TypeScript, Vite. Its runtime dependencies are marked (the app's document view), noVNC (the live view) and @modelcontextprotocol/ext-apps (the MCP App). It holds no router or state library: routing is a small module of its own and shared state is classes using Svelte runes.

UI-3. npm --prefix ui run build makes three bundles into kubed/selenium_flow/http/static/, which is gitignored and never committed. The files have fixed names:

Surface Files Loaded
admin admin.html, admin.js, admin.css inlined into the page
app app.html, app.js, app.css inlined into the MCP App shell
live live.js, live.js.LICENSE.txt fetched by the page when the Live tab opens

UI-4. The admin and app builds each produce one script and one stylesheet with no shared chunk, because the server inlines them. live.js is separate so the page loads without noVNC. The admin build alone copies the two shells from ui/public/. npm run build empties the output folder first.

UI-6. A surface is built when all three of <name>.html, .css and .js exist. The server logs one INFO line at start when the admin surface is not built.

How it is served

UI-7. GET <mount>/ answers the page with no credential, since it is the sign-in form and every datum it shows is fetched with a credential afterwards. GET <mount>/admin answers a 301 to ./, so the page has one address.

UI-8. The server builds the page from admin.html once per set of substitutions and per version of the three files (their mtime and size). It removes the shell's own HTML comments, inlines the stylesheet and script, and fills three placeholders, which land as data-mount, data-console and data-oidc on the root element and are read once at boot:

  • __MOUNT__, the mount prefix;
  • __CONSOLE__, grid.console_url (default /);
  • __OIDC__ (AUTH-33).

Substitutions are HTML escaped, nothing inside the bundle is substituted, and a literal </script in the script is escaped.

UI-10. The page is sent with Cache-Control: no-cache and a strong ETag of the built HTML. A request whose If-None-Match names it gets a 304. A rebuilt UI is served on the next load.

UI-11. The page is sent with the headers AUTH-33 lists: Content-Security-Policy: frame-ancestors, X-Content-Type-Options and Referrer-Policy. The placeholder page of UI-13 carries the same.

UI-12. GET <mount>/live.js serves the live bundle with no credential, no-cache, an ETag and text/javascript, and a 304 on a matching If-None-Match. Without a build it is a 404 with an error.

UI-13. When the admin surface is not built, GET <mount>/ answers 200 with a page whose title and only heading are Selenium Flow. The rest of the server is unaffected.

UI-14. When the app surface is not built, the MCP App is not registered and the file tools and show behave as with mcp.apps off: they return their data.

UI-15. The page works at a root mount and behind an ingress that strips a prefix. Its base is its own path with trailing slashes removed. Server-issued URLs already carry the mount, so the app resolves them against that path with the mount taken off.

The page

UI-16. The page is one header (the name selenium-flow and, once signed in, Sign out) over one of two things: the sign-in card or the signed-in page.

UI-17. The signed-in page has four top tabs: Workspaces, Secrets, Settings and Grid console. The Grid console tab is hidden when grid.console_url resolves to the page itself, and then no frame is made, since framing the page nests it without end. Otherwise the console frame is mounted once and hidden when another tab is up, so switching tabs does not reload the Grid's console.

UI-18. Routes are the address's hash, so no route reaches the server. The hash is read at boot and on every hashchange:

Hash View
#/ and anything unknown the workspace list
#/console, #/secrets, #/settings that top tab
#/workspaces/<key> a workspace, on Session
#/workspaces/<key>/<tab> a workspace tab: session, files, flows, site-data, history, console, network or live
#/workspaces/<key>/flows/<name> Flows with that flow open
#/workspaces/<key>/site-data/<host> Site data with that host open
#/workspaces/<key>/network/<id> Network with that request open

An unknown tab reads as Session. A key or segment that does not decode reads as the list.

UI-19. Opening a workspace builds its detail view afresh and destroys the previous one, with its loads, lightbox and modal. Nothing started for one workspace can land on another's screen.

Signing in

UI-20. The card shows a password field MCP token, an Enter button, and, when data-oidc is set, a Sign in with OIDC button below. A refused token shows That token was refused.; any other message the app has to say shows in the same place.

UI-21. The token's life on the page, its probe and sessionStorage['sf-token'] are AUTH-34. The token is never written to localStorage.

UI-22. Every call sends the credential as a bearer. A 401 on a token sign-in signs out (AUTH-34), and Sign out is AUTH-44. The OIDC steps (PKCE, the reply checks, renewal, the messages) are AUTH-35 to AUTH-43.

The workspace list

UI-24. The list heads with Workspaces and a connection indicator (UI-33), and shows Loading… until the first answer, the error text when the load failed, and No workspaces yet. when there are none.

UI-25. Each workspace is one card, in the server's order (most recently used first), and a click anywhere on it opens the workspace. A card shows:

  • the browser's mark (a glyph for Chrome, Firefox, Edge and Safari, a globe otherwise);
  • the name pill: the workspace's name, else its owner, else workspace;
  • the Grid session id, or no browser;
  • a state pill: open, idle or unknown (a browser the Grid's listing could not confirm);
  • a capture pill when capture was asked for: ● capture while entries are arriving, capture paused otherwise;
  • a meta line: browser and version, counts per file kind (zero counts left out), the age of the start, the node, and by <opener> (token or the OIDC username);
  • the last page's URL.

UI-26. A workspace opens on a masthead and a row of tabs. The masthead repeats the mark, the name, the state pill, a ● REC pill while a recording runs, the capture pill, and the last page as a link only when it starts http:// or https:// (else as text, or nowhere yet). It is blank until the workspace's row arrives.

UI-27. The detail view has a Back button to the list and an End browser button, disabled unless a browser is attached. It asks through the browser's confirm, then sends DELETE /admin/workspaces/{key}/session (WS-17). The workspace and its context stay. A failure alerts Could not end the browser: <error>. A success closes the overlays about the browser's downloads and reloads Files and Flows.

A workspace's tabs

UI-28. The tabs, in order, each routed by UI-18:

Tab What it is for Count Routes and rules
Session What the workspace asks for, what the Grid gave, and every capability the last open sent none the pushed row
Files Downloads, Screenshots, Recordings and Files files in the row workspace-files.md
Flows The saved flows and the open one flows, or off saved-flows.md
Site data What is saved per host hosts site-data.md
History Where the workspace has been hosts site-data.md
Console The page's console entries capture.md
Network The page's requests requests capture.md
Live The browser's screen none live-view-and-control.md

UI-30. Console and Network are disabled (aria-disabled, muted, with a title) when the row says capture is off, and their pane then says Capture is off for this workspace. Open the browser with open_session(capture=true). Live is disabled with a title that gives the first reason that holds, in this order: no live view · switched off, no live view · grid not answering, no live view · no browser, no live view · headless, no live view · this Grid has no VNC.

UI-31. The Session tab shows a workspace group and, once a browser has been opened, a Grid group, then a Capabilities section that starts closed. A fact with no value is left out.

  • The workspace group: the key and who holds it (only for an unnamed workspace), the browser asked for with its version (latest when none), the window, insecure, headless, record and capture (the last two only while a browser is up). Each setting a caller or the server chose carries a pill naming where it came from.
  • The Grid group: the browser and version, the session id, the node, the start time, the idle timeout, and then grid: not answering, or live view: yes/no, or how the last session ended (ended by the admin, ended by the caller, reaped after N s idle, gone from the Grid).
  • The Capabilities section lists each capability the last open sent with its source pills. A vendor block (goog:chromeOptions, moz:firefoxOptions) shows what it holds by count (args 3 · prefs 6), never its values. With none sent it says Nothing sent yet: no browser has been opened in this workspace since this server kept it.

UI-32. Which panes stay mounted: Session, Files, Flows, Site data and History stay mounted and are hidden when another tab is up, so a folded section stays folded. Live, Console and Network are mounted only while shown, so leaving the tab closes a live socket or stream.

How the page stays current

UI-33. The workspace list is pushed. GET /admin/workspaces answers the rows, live_enabled and events_url, a signed path for the stream because EventSource cannot send a header (AUTH-29). The page opens events_url once, resolved against the page's base, and applies every message as the new list. The indicator is a dot while the stream is live, connecting… before it opens and reconnecting… after an error.

UI-34. One server task computes the list every 2 seconds for all connected pages, and only while a page is connected. A page receives a message when the payload differs from its last. A keepalive comment goes out after 20 seconds of no change. A route that changes what the list shows (End, Forget, Clear, Keep, Delete, and a flow's save, move or delete) discards the last computation so the next one is fresh.

UI-35. A fallback runs every 30 seconds. When nothing has arrived for 45 seconds the indicator reads polling, the page refetches GET /admin/workspaces, applies it, and reopens the stream on the freshly signed events_url, because the signed URL expires.

UI-37. A pushed row carries revisions: files_rev, flows_rev, site_data_rev and history_rev. An open workspace reloads a tab's data only when that tab's revision moved, so a push that changed nothing for the tab costs nothing:

  • Files reloads when files_rev, which also holds the browser id, changes.
  • Flows reloads when flows_rev changes, which covers the workspace's flows and the shared ones.
  • Site data and History both reload when either revision changes, since each reads the other.

UI-38. When a push shows a different browser id, or live flipped, the page closes the lightbox and any confirm that acts on the browser's downloads, blanks the Downloads grid, and forces a reload of Files. A different browser is a different download store.

UI-40. Loads for one panel overlap safely. Each new load aborts the one before it, only the newest paints, and an awaiting caller can wait until the newest has settled. A load tied to a workspace is aborted when its view is destroyed.

Conventions every tab follows

UI-42. A tab that has loaded nothing says Loading…. A failed load shows the server's error text (error of the response, else request failed (<status>)) where the data would be. A tab with nothing to show says so in one sentence. The sentences:

Where Text
Workspaces No workspaces yet.
Downloads No downloads., or No browser — downloads go with it. when none is attached
Screenshots, Recordings No screenshots yet., No recordings yet.
Files Nothing here yet — prints land here, and anything you keep.
Flows Flows are off: this server was started with no DATA_DIR., No flows yet.
Site data Nothing saved — an agent calls save_site_data after signing in.
Secrets No secrets are configured on this server.
Console, Network No messages since the last navigation, No requests since the last navigation

UI-43. A destructive action opens one confirm box, never two. The box names what goes and, where it matters, what stays. Its confirm button is the verb and the count (Clear 3 files, Delete 2 screenshots, Forget, Clear, Delete), is danger-coloured, and is disabled while the action runs. Cancel, Escape and a click on the backdrop all cancel. A failed confirm leaves the box open and shows the error in an alert, so an edit is not lost. Only one box is open at a time.

UI-44. A confirm opens for each of these, with a body that says:

  • Clear downloads: lists each download with — gone, or — copy in Files stays when Files holds one of that name, or says there is nothing to clear.
  • Clear screenshots, Clear recordings: the count, and that anything kept in Files stays.
  • Delete a file (Files): that it goes for good and has no undo.
  • Forget site data, Clear site data, Clear history: which entries go and which stay, as goes and stays rows.
  • Delete a flow: that it is removed from the folder it lives in, and that a global flow goes for every workspace.
  • Move a flow: which library it moves to and that other workspaces stop or start seeing it.

End browser uses the browser's confirm, not the box.

UI-45. A button that acts is disabled when it cannot: End browser with no browser attached; Clear downloads unless the browser is running, this workspace's files have loaded and no load is in flight; Clear screenshots and Clear recordings when there are none or a load is in flight; Paste unless Control is held.

UI-46. A section is an accordion: a button with aria-expanded and aria-controls, a caret, a count pill and its actions. All start open except Capabilities and every Site data and History row past the first. A fold is remembered by id for the life of the page, so a section that remounts keeps its state.

UI-47. The page writes data as text. It renders no HTML from data: {@html} is forbidden by lint, and captured console text, requests, cookies and flow arguments are shown as text nodes. A URL is a link only when it starts http:// or https://.

UI-48. A value is shown as a word or a mark where one will do. The Settings tab shows ●●●● for a sensitive value that is set and — for one that is not. A connected stream is a dot with no words, and Secrets and Settings show no value a person could paste.

UI-49. Motion is polish only. A transition lasts at most 150 ms, runs only on a change within the page (not on first paint or a route change), and is zero under prefers-reduced-motion.

Secrets and Settings

UI-51. The Secrets tab shows GET /admin/secrets under a heading and one sentence, one card per secret: its name, warning pills (unusable until fixed, key unresolved, inline value), its description, the reason it is refused, its key pills with their source when not a file, its allowed leash (— when none) and from, where its definition came from. The catalogue is in secrets-and-scope.md.

UI-52. The Settings tab shows GET /admin/settings: a card per section, a row per setting with its name, value and a source pill (default, config, env or args, weakest first, which is the order of precedence), and an i that shows the setting's description. It is read-only and links to the wiki's Configuration page. What it lists is in config.md.

The flows editor

UI-53. The Flows tab is a list and a panel side by side. A list row shows the flow's name, its step count and a globe when the flow is shared. Picking a row, even the open one, loads the flow document and puts its name in the hash without adding a history entry.

UI-54. The panel shows the name, a 🌐 global pill when shared, the description, and three buttons: edit, move and delete. Move is hidden in the global workspace. Below sit Params, then Steps, and a detail pane that reads Pick a parameter or a step to see what it holds. Params say This flow takes nothing. when none.

UI-55. A parameter row shows a type glyph and a required marker. A step row shows its action's glyph (❓ for a name the runner does not run), its id chip and a lock when the step types a secret. Clicking a row shows its detail, and clicking the shown one hides it. A step's detail shows its number, tool, note, arguments (a selector as css … or xpath …, a secret as name / key) and onError and return only when set. A parameter's detail shows its type, required or optional, description, default and the steps that read it, each a link to the step.

UI-56. Edit reads the flow again before it opens, so the editor holds the raw file with its comments and not the copy on screen. A failed read alerts Could not read that flow: <error>. Save sends the text as PUT {yaml}, and the box stays open with an alert on error.

UI-57. Move sends POST …/move {to} and delete sends DELETE. Afterwards the flow closes, the hash returns to …/flows and the list reloads. A listing that does not hold the open flow closes it and resets the hash; otherwise the listing reload also reloads the open flow. A deep link to a flow opens it only once the listing says it exists.

UI-58. A flow file's shape is never trusted. A steps that is not a list, a parameters that is not a mapping, a null step or a key such as constructor does not break the panel; the editor is the way to fix it.

The MCP App shell

UI-60. The MCP App is the app surface. It draws one view by the component name in a show result (context, console, network, request, file, files, folder, flows, flow, sites, site, secrets, document), from the data the result carries. The views are read-only: no clear, keep or delete. The table from URI to component is in mcp/show.py (surfaces.md).

UI-66. The shell drills down by calling show through callServerTool, never sendMessage.

UI-67. The shell shares the shown URI with updateModelContext, best effort. Nothing depends on it.

UI-68. claude.ai ignores size-changed and reads the document's height, so the app sets documentElement.style.height as well as letting autoResize report it.

UI-69. read_resource carries no app. It is the model's reading tool, and an app on it would be drawn on every read.

The design source

UI-62. The design is a Penpot file named Admin UI, whose Admin page holds the top-level views.

UI-63. (proposed) Where the drawing and the code differ, the code is the truth, and the drawing is redrawn in the round that notices. A change to a view edits the drawing, and a change to behaviour edits this file.

Proposed: several sessions in a workspace

Not built. The reasoning, and the questions still open, are in the multiplayer design.

UI-64. (proposed) A workspace with more than one session shows a dropdown of its sessions in the row with ← Workspaces (UI-27). With one session there is no dropdown. Picking a session refocuses the session's tabs (UI-65) on it.

UI-65. (proposed) Session, Console, Network and Live are the picked session's tabs. Files and Flows are the workspace's. Replaces, when built, UI-28's table for those six tabs. Where Site data and History belong is open.

Proposed: flow tags and the workspace's config

Not built. See the flow tags design and the workspace config design.

UI-70. (proposed) The Flows tab filters its list by tag (FLOW-52).

UI-71. (proposed) The admin UI edits a workspace's config (WS-61), and a change takes effect without a restart.

Clone this wiki locally