Specification · RFC
RFC-0012: Workspace Web Console
Version: 0.4.0 | Status: normative | Phase: stable Owners: @Zihua Wu
1. Summary
Section titled “1. Summary”[RFC-0012:C-SUMMARY] Summary (Informative)
Section titled “[RFC-0012:C-SUMMARY] Summary (Informative) ”inferlab web starts a local, token-protected service that presents one or more registered workspaces in a browser. It shows the same operations, records, and definitions as the view-only TUI governed by RFC-0010, compares Bench records across workspaces, and launches a bounded set of InferLab workflows by invoking the InferLab CLI as detached jobs. The CLI stays the only action authority, records stay the only evidence authority, and the service itself writes neither.
Since: v0.1.0
2. Specification
Section titled “2. Specification”[RFC-0012:C-SCOPE] Service And Action Authority (Normative)
Section titled “[RFC-0012:C-SCOPE] Service And Action Authority (Normative) ”The public CLI MUST provide web, which starts a local service presenting registered workspaces in a browser and runs until interrupted. Neither the web invocation nor the internal invocation that supervises a launched job publishes a workspace operation; every workflow such a job runs publishes its own under RFC-0010:C-OPERATIONS.
web MUST print exactly one line on stdout, the access URL governed by RFC-0012:C-ACCESS, once its listener accepts connections, and nothing else on stdout. Diagnostics MUST go to stderr. A failure to bind its listener or to read its workspace registry MUST end the invocation with a typed error before the URL is printed.
The service MUST NOT write records, workspace definitions, local bindings, or Pixi state, and MUST NOT reconstruct execution facts from definitions. Every workflow it launches MUST be an invocation of the InferLab CLI governed by the owning workflow RFC, and that invocation writes its own records under RFC-0005:C-EVIDENCE. The service MUST NOT perform a workflow effect itself.
A directory listing, a dry-run preview, or a workspace refresh that is still pending MUST NOT block other refreshes, other sessions, or other actions; the operator MUST be able to abandon a pending listing or preview, and its failure MUST be reported.
Rationale: A browser surface is valuable for monitoring, comparison, and remote access, but a second implementation of lifecycle, cleanup, or record writing would split authority. Invoking the CLI keeps one action authority and makes a browser-launched run indistinguishable from a terminal-launched one.
Since: v0.1.0
[RFC-0012:C-ACCESS] Local Binding And Token Access (Normative)
Section titled “[RFC-0012:C-ACCESS] Local Binding And Token Access (Normative) ”The service MUST listen on a loopback address unless the operator selects another address with --bind; with a non-loopback address it MUST warn on stderr that its traffic is not encrypted. It MUST accept --port; when the port is omitted it MUST choose a free port.
At each start the service MUST generate an access token with at least 128 bits of entropy from the operating system’s secure random source, and the URL it prints MUST carry that token as a query parameter. It MUST NOT persist the token or write it to any diagnostic. On a request that presents the token in the query, the service MUST set a cookie carrying it, HttpOnly and SameSite=Strict, with a name unique to that service instance, and MUST redirect to the same location without the token. Every other HTTP request, including every event stream, MUST present that cookie. A request without a valid token MUST receive HTTP 401 and no workspace content. Every request that launches, cancels, registers, or removes MUST also carry an Origin whose host and port equal the request’s Host header; reads, including event streams, are protected by the SameSite=Strict cookie, because browsers do not send an Origin on a same-origin read. Every response MUST carry Referrer-Policy: no-referrer.
A holder of the token has every capability of the service.
Rationale: GPU hosts are commonly shared, so a loopback listener alone would let any local account launch work under the operator’s identity. A per-start token, as notebook servers use, keeps access explicit; SSH port forwarding reaches the loopback listener without exposing it, which is why the Origin is compared with the forwarded Host rather than with the listening address.
Since: v0.1.0
[RFC-0012:C-WORKSPACES] Workspace Registry (Normative)
Section titled “[RFC-0012:C-WORKSPACES] Workspace Registry (Normative) ”A workspace root is a directory that contains .inferlab/workspace.toml, whether or not its definitions load. Its canonical form is absolute with every symbolic link resolved.
The service MUST present every registered workspace. When web selects a workspace through the discovery or --workspace selection governed by RFC-0002:C-WORKSPACE-AUTHORITY, the service MUST register that workspace and the access URL it prints MUST open that workspace’s views; started where neither selects one, it MUST register none and the URL MUST open the workspace list.
The page MUST offer a directory browser for registration. It MUST list only the names of directories under the directory the operator navigates to, MUST mark which of them are workspace roots, and MUST NOT read file contents. Registration MUST accept only a workspace root and MUST record its canonical form; registering a root already registered MUST succeed without change. Removing a workspace MUST only unregister it, MUST NOT modify its files, and MUST NOT affect its running jobs.
The registry MUST persist as the user-level state file inferlab/web/workspaces.json under XDG_STATE_HOME, or under ~/.local/state when it is unset, and MUST hold only canonical workspace roots. Each write MUST replace the file atomically. A malformed registry MUST fail the start, naming the file, and MUST NOT be overwritten. A registered root that later fails to load MUST remain registered and MUST be presented as unavailable with its failure.
Each record, operation, job, and definition MUST be identified by its workspace root together with its identity within that workspace, and every surface that combines workspaces MUST show which workspace each object belongs to.
Rationale: Operators move between several workspaces on one host; a remembered list removes repeated setup, and per-workspace identity keeps equally named records apart.
Since: v0.1.0
[RFC-0012:C-VIEWS] Views, Records, And Comparison (Normative)
Section titled “[RFC-0012:C-VIEWS] Views, Records, And Comparison (Normative) ”For each registered workspace the page MUST provide Overview, Operations, Records, and Workspace views with the content, authority labels, and record hierarchy that RFC-0010:C-READ-MODEL requires of the corresponding TUI views. Each workspace MUST form its own display generations under the refresh, observation-state, and active-server deadline rules of RFC-0010:C-REFRESH, applied per workspace, on the interval web accepts as --refresh-interval with the TUI’s default; the page MUST show each workspace’s refresh indicator and MUST offer an immediate refresh. A workspace that fails to load or refresh MUST NOT affect another.
A record MUST have a page that presents its detail, its recorded case metrics, and its explicitly referenced logs. Logs MUST be associated only through explicit references and MUST be shown as a bounded tail that the operator pages on demand.
The page MUST let the operator select Bench records, from one or several workspaces, and compare one metric across them. Each series MUST be one record, labeled with its workspace and record, with points placed by their recorded effective load, the concurrency or request rate the record’s case evidence carries, rather than by case identifier. Records whose loads are of different kinds MUST NOT share one load axis. A missing value MUST be shown as missing rather than zero. The comparison MUST use the metric mapping of RFC-0010:C-READ-MODEL, MUST NOT add an SLO interpretation, and MUST NOT create or modify evidence.
The page MAY offer browser notifications when a job ends or a running server’s observed process dies. Notifications MUST stay off until the operator enables them in that browser.
Rationale: The browser presents the same facts as the TUI, so a fact reads the same on both surfaces, and comparing records answers the sweep questions a single-record view cannot.
Since: v0.1.0
[RFC-0012:C-ACTIONS] Launched Workflows And Jobs (Normative)
Section titled “[RFC-0012:C-ACTIONS] Launched Workflows And Jobs (Normative) ”The page MUST offer serve start, serve stop, recipe run, bench, and scratchpad note, and no other workflow. Each action MUST be built from typed form fields into an argument vector for the executable of the running service, MUST pass --workspace with the canonical workspace root, and the page MUST NOT accept a free-form command line or shell text. A scratchpad note carries its text, an optional topic, and optional record references.
Before launching serve start, recipe run, or bench, the page MUST run the same argument vector with --dry-run and show its output and the vector it will launch. When the dry run fails, the page MUST NOT offer the launch. The launched vector MUST equal the previewed one without --dry-run; the launched invocation resolves again, and the preview does not bind it.
A launch MUST create one job directory, .inferlab/runtime/jobs/<job-id>/ in that workspace, holding the launched argument vector, its start time, the producer identity of the launched process (host identity, boot identity, process identifier, and process start time, as in RFC-0010:C-OPERATIONS), its stdout and its stderr in separate logs, and its exit status once it ends. The job MUST run in its own process group, detached from the service, so that stopping or restarting the service does not stop it. A launch that cannot start MUST show its error and MUST NOT leave a job directory. The service MUST NOT serialize or deduplicate concurrent launches; the invoked CLI’s own locks govern them. The service MUST NOT delete job directories. The invoked CLI, when run as a job, MUST record in the job directory the identifier and directory of the first top-level record it creates, if any, so a job leads to its record. A job launched by a detached CLI invocation under RFC-0003:C-RUNTIME-WORKFLOWS MUST follow this same contract. A job log and its status are run-time conveniences, not evidence.
A job MUST be shown as running, as exited with its status, as ended with an unknown status, or, when it has no recorded exit status and its recorded process belongs to another host or boot, as not observable from this host; the service MUST NOT infer an outcome. After a restart the service MUST rediscover the jobs of each registered workspace from their job directories. Cancelling MUST deliver to the job the interrupt a terminal Ctrl+C delivers, MAY be repeated, MUST NOT escalate to a kill, and MUST leave cleanup to the invoked CLI. Before signalling, the service MUST validate the recorded producer identity; a job whose identity does not match, or that was launched on another host or boot, MUST NOT be signalled.
Rationale: The typed action set covers the operator’s serve, measure, and note workflow without turning the page into a remote shell, the dry run shows exactly what will run before GPUs are committed, and detached jobs keep hour-long sweeps independent of the browser service. Producer identity keeps a reused process identifier from turning a cancel into a signal to an unrelated process.
Since: v0.1.0