Agent ↔ UI protocol (v1)
The source of truth is agent/pkg/protocol/protocol.go; TypeScript types are generated from it (yarn protocol:gen → packages/client/src/protocol.gen.ts). This page explains the behaviour the types cannot. Background: performance.md §9.
Connection
- One data socket per browser tab:
GET /ws, WebSocket, binary frames only. - Desktop /
v8s serve: the client offersSec-WebSocket-Protocol: v8s.v1, token.<hex>. The agent rejects a missing or wrong token, and anOriginthat is not the agent's own origin (or the Electron app origin), with 403 before upgrading. It echoesv8s.v1. - Fake mode (
v8s agent --fake …, used by tests and UI development) still requires the token, but it is printed to stdout like in desktop mode. - On upgrade the agent sends
Hello. The client checksversion == 1and closes on mismatch.
Frames
[u8 kind][u32 channel BE][u32 seq BE][msgpack payload]. seq increments by one for every frame the agent sends. The client sends seq = 0 except on acks.
| Kind | Direction | channel | Payload |
|---|---|---|---|
| 1 Hello | agent → client | 0 | Hello |
| 2 Request | client → agent | request id | Request |
| 3 Response | agent → client | request id | Response |
| 4 Patch | agent → client | qid | ViewPatch |
| 5 Ack | client → agent | 0 | none (seq = acked patch frame) |
| 6 Dict | agent → client | 0 | DictAdd |
| 7 ClusterState | agent → client | 0 | ClusterStates |
| 8 Object | agent → client | oid | ObjectFrame (not acknowledged) |
| 9 Job | agent → client | 0 | JobFrame: the whole current state of one job (not acknowledged) |
msgpack: maps with the field names in the Go tags; ids is a msgpack bin. Go uses github.com/vmihailenco/msgpack/v5, the client msgpackr (with useRecords: false, mapsAsObjects: true).
Views
view.subscribe {qid, gen, query, window}→{columns}. The agent then sends a full first patch (withids) as soon as rows exist, and later patches as things change.- Coalescing: the first change after a quiet period flushes within 16 ms; after that at most one patch per subscription per tick. The tick is 100 ms for loopback clients and 250 ms otherwise (P0 only implements loopback). A paused subscription (P1: hidden tab) gets no ticks.
- Backpressure: at most 3 unacknowledged patch frames or 512 KiB in flight per socket; beyond that the subscription stays dirty and the next tick sends the newest state. Never a backlog.
- Generations:
view.updatewith a newquerymust bumpgen; the agent ignores an update whosegenis lower than the subscription's current one. Updates of one subscription apply in request order: while one is resolving a first-time generic kind (up to 20 s) later ones queue behind it, and a later one that changes the query supersedes it (the superseded request answersconflict). Patches carry thegenthey were computed for; the client drops patches older than its currentgen. - Windows: the client asks for
limitrows fromoffset. WithanchorIdset (the first visible row),offsetis relative to the anchor's current index, so inserts above the viewport never move what the user is reading. The agent clamps the window to the view. If the anchor row is gone, or it changed and re-sorted outside the window the client holds, the window keeps its previous position instead of chasing it. - Ids: per subscription, monotonic, never reused. A row's id stays stable while the object exists in the view (including across re-sorts and query changes on the same subscription).
- Rows:
[id, version, …cells]incolumnsorder;versionincreases when any cell changes. The client keeps rows by id and re-renders a row only when its version changes.
Events of one object
view.subscribe with gvr: "v1/events" and query.involved: ObjectRef ({cluster, gvr, namespace, name}) is the view of every event, Normal and Warning, of that one object, listed on demand while the view is open (the global v1/events view is Warning-only). The agent resolves the object's Kind and scope itself and starts a namespaced, reference-counted LIST + WATCH of its events (involvedObject.kind, .name, .namespace; no uid: the kubelet records Node events with the node name as uid). The query is then rewritten into a plain filtered view (clusters = [involved.cluster], the events namespace, and an object eq Kind/name filter) over one shared per-cluster events store, so patches, windows, backpressure and the columns (the v1/events columns, including source) work as in any other view. text, filters and sort still apply; clusters and namespaces are ignored.
- The events namespace is the object's own, or
defaultfor a cluster-scoped object (Node, PersistentVolume, Namespace, cluster-scoped custom resources). The kind and its scope come from the agent's registry or discovery, never from the client. - The agent keeps the newest
MaxObjectEvents(200) events per object bylastSeen. view.subscribeanswers only after the first list, an error, or 15 s, so the client has a real loading state and a real error. An error response means no subscription exists.bad_request:gvrother thanv1/events, a missing name or namespace, a kind that has no events (helm.sh/v1/releases,v8s/v1/problems), or a direct query of the internalv8s/v1/objecteventskind.not_found: the cluster is not selected, or the kind is unknown.forbidden: no permission to list events in that namespace.unavailable: the 15 s timeout or the watch budget is exhausted.view.updatethat changes theinvolvedobject (cluster, gvr, namespace or name) re-resolves like a changed kind; one that keeps it only changes sort, filters or the window.- Unsubscribing releases the watch, which lingers 30 s (it counts against the per-cluster watch budget and is evicted first). These rows live in their own store: they never reach the Warning-only tier-0 events or the problems engine.
Requests
Every request is a Request{method, params} on a fresh channel id answered by one Response{result | error}. Errors are {code, message, hint?, live?, applied?}; codes: bad_request, not_found, forbidden, unavailable, internal, invalid (the API server rejected the object), conflict, write_unavailable, write_confirm, link_mismatch, gitops_managed. Slow requests (object operations, a generic kind's first view) are answered asynchronously, so responses may arrive out of order with patches; match them by channel id.
| Method | Params → result |
|---|---|
clusters.list | → {clusters, selected}. selected is the live selection, else the remembered one from settings. Each cluster has groups and writeContext? from settings; contexts that are linked write contexts are not listed. |
clusters.select {ids} | → ClusterStates. Starts the tier-0 watches of new clusters; deselected clusters stop after a 10 s grace. The selection is stored in settings. |
kinds.list | → {kinds}: the union over the selected clusters' discovery. Kind{gvr, group, version, kind, plural, shortNames, namespaced, available, curated, clusters, ips}; ips is true for kinds whose rows carry IP addresses (IP search, IP-aware filter); available is true for every listable kind (list + watch), clusters are the selected clusters that serve it. Until a cluster's discovery has loaded, its curated kinds are listed. |
view.subscribe / view.update / view.unsubscribe | as in Views. view.subscribe returns the kind's columns; for a generic kind it waits (up to 20 s) for the first columnDefinitions, and answers not_found when no selected cluster serves the kind. view.update with a changed gvr or clusters re-scopes the watches and, if the gvr changed, returns the new {columns}. A query with involved is the events of one object. |
object.get {cluster, gvr, namespace, name, keepManagedFields?} | → {yaml, uid, resourceVersion, managedBy: [{manager, operation, fields}], owners: [{kind, name}], gitops?: {kind, name, namespace}}. gitops comes from Flux (kustomize.toolkit.fluxcd.io/name+/namespace → Kustomization, helm.toolkit.fluxcd.io/... → HelmRelease) and Helm (app.kubernetes.io/managed-by: Helm + meta.helm.sh/release-name → Helm) metadata. managedFields is stripped from yaml unless requested; managedBy always lists the field paths per manager. |
object.subscribe {oid, ref, keepManagedFields?, reveal?} / object.unsubscribe {oid} | Empty result. The agent then sends KindObject frames on channel oid: the same payload as object.get (plus deleted?, error?) for the initial state and after every change, from a single-object watch (fieldSelector=metadata.name=) on the read context. A watch that cannot start (not found, forbidden) sends one frame with error. The agent's caches hold projections, not objects, so a curated kind's cache is not used. |
object.dryRun {ref, yaml, mode} | → {ok, warnings, error?, conflicts: [{path, manager}]}. Server-side dryRun=All (update: PUT against the live resourceVersion; create: server-side apply). For updates, conflicts lists the changed paths that another field manager (not v8s) owns according to the live managedFields. A server rejection (invalid, admission, forbidden, quota) is ok: false with error, not a failed request; only a 401 or an agent-side failure is an error response. |
object.apply {requestId, ref, yaml, mode, resourceVersion} | → {resourceVersion, usedContext, applied?}. mode: "update" is a PUT with the opened resourceVersion and field manager v8s (kubectl edit semantics). mode: "create" is server-side apply (field manager v8s, force=false) of every document of a multi-document YAML. A 409 is {error: {code: "conflict", live}} where live is the current object payload (masked). A multi-document apply that fails at document k answers {error: {…, applied}} with the documents that were applied before it. |
object.delete {requestId, ref, propagation?} | → {usedContext}. propagation: Background (default), Foreground, Orphan. |
object.action {requestId, ref, action, params} | → {usedContext, resourceVersion?, name?}. Actions: scale {replicas} (deployments, statefulsets, replicasets), restart (patches kubectl.kubernetes.io/restartedAt; deployments, statefulsets, daemonsets), cordon / uncordon (nodes), suspend / resume (cronjobs), trigger (creates a Job from a CronJob; name is the Job), rollback {revision} (deployments; restores that ReplicaSet's pod template). Flux actions (any Flux kind): flux.suspend / flux.resume (merge patch spec.suspend), flux.reconcile (annotation reconcile.fluxcd.io/requestedAt), flux.reconcileWithSource (reconciles the referenced source first, waits for its status.lastHandledReconcileAt, then the object), flux.force and flux.reset (HelmRelease only: forceAt / resetAt and requestedAt carry the same token). Reconcile-style actions return the token; the object is handled once status.lastHandledReconcileAt equals it (the payload YAML and the lastHandled / requestedAt columns carry both, so the UI shows "Reconciling…" until then). All are minimal merge/JSON patches. |
access.check {checks: [{cluster, verb, gvr, namespace?, name?}]} | → {results: [{allowed, viaWrite, reason}]} in input order. SelfSubjectAccessReview on the read context, then on the linked write context when denied; cached 60 s. |
stream.open {type, …} | → {streamId, usedContext, downloadUrl?, localPort?, forwardId?}. Opens a stream. |
portforward.list | → {forwards: [{id, ref, port, localPort, pod, state, usedContext, error?}]}. |
portforward.stop {id} | Empty result. |
jobs.start {requestId, type, params, useWriteContext?} | → {jobId}. See Jobs. |
jobs.list | → {jobs: JobFrame[]}: every job, running first. |
jobs.cancel {jobId} | Empty result. |
drain.preflight {cluster, node, options} | → {node, cordoned, usedContext, evict, blocked, unmanaged, emptyDir, daemonSets, mirror, finished}; each list holds {namespace, name, owner?, pdb?: {name, disruptionsAllowed}, emptyDir?}. blocked pods are covered by a PDB with no disruption allowed, unmanaged have no controller, emptyDir is an overlay on the other lists, daemonSets/mirror are skipped, finished are deleted. Read-only. |
flux.inventory {ref} | → {entries: [{id, group, version, kind, namespace?, name, gvr?, live, tone, status?}], revision?} of a Kustomization (status.inventory.entries), each entry joined to its live object and health when its kind is watched. |
flux.graph {cluster} | → {nodes: [{id, kind, gvr, namespace, name, tone, suspended}], edges: [{from, to, type}]}: dependsOn and sourceRef edges of the cluster's Flux objects. |
helm.release {cluster, namespace, name, revision?} | → HelmRelease: chart, chartVersion, appVersion, values (user) and computedValues (YAML), manifest, notes, hooks, history, managedBy (Flux, from the release labels). The payload is decoded lazily and cached (LRU, 64 MiB, by Secret uid + resourceVersion). |
helm.diff {ref, fromRevision, toRevision} | → {values, manifest} unified diffs ("" when identical). ref is {cluster, gvr: "helm.sh/v1/releases", namespace, name}. |
problems.classes | → {classes, unavailable}. classes is the registry: {class, family, title, severity, default, enabled, counts: {clusterId: {total, acked}}, enabledIn?}. enabled is the effective global setting, enabledIn the clusters whose per-cluster override differs. Counts are maintained incrementally by the engine. unavailable lists checks that cannot run ({cluster, kind, reason}, a baseline kind the user cannot list). See Problems view. |
problems.evidence {id} | → {id, cluster, class, subject, title, message, since, conditions, containers, events, related, error?}: the triggering conditions and container states from the live object (a pod of the group for rollups), the last 5 related Warning events (agent event cache) and related objects (rolled-up pods, owners, Services). not_found when the problem is gone. |
problems.ack {id, until?} / problems.unack {id} | Empty result. An acknowledged problem keeps acked = "true" (the view's acked column and the class counts) until its severity rises, its count grows by 50% (at least 1), until (unix ms, a snooze) passes, or it resolves and recurs. Acknowledgements are persisted in settings.acks keyed by the stable problem id. |
security.images {clusters?} | → {images}: the Vulnerabilities overview. Images (repository:tag) deduplicated across workloads and clusters (workloads, reports, clusters, critical/high/medium/low/unknown), ranked by critical then high; one row per source (trivy | kubescape) when both scanners run. Computed from the Table-mode report rows, no vulnerability array is transferred. |
security.reportDetail {ref, offset?, limit?} | → ReportDetail {kind, source, resourceVersion, summary, total, offset, …}: the lazily fetched body of one report (ref.gvr names its kind). kind is vulnerabilities (CVE, severity, package, installed, fixed, title, link), checks (config audit / RBAC / infra checks), secrets, policyResults (Kyverno results of one policy report) or document (a YAML rendering of a Kubescape ApplicationProfile / NetworkNeighborhood). Rows are chunked (limit default 300, capped at 1000): repeat with offset += rows until offset + rows >= total. The decoded report is cached by resourceVersion (bounded LRU), so chunks cost one fetch; concurrent requests for the same report share one fetch, and at most 4 report fetches per cluster run at a time. |
kyverno.setMode {ref, mode, rule?, useWriteContext?} | → {usedContext, resourceVersion, mode}. mode is Audit or Enforce: sets validationActions of a CEL ValidatingPolicy (rule must be empty). Legacy kyverno.io/v1 ClusterPolicy / Policy are read-only and refused (bad_request with a "migrate to CEL" hint). Honours ref.uid. |
kyverno.exceptionTemplate {policy, rule?, resource} | → {yaml, apiVersion, kind, namespace?} (kind is PolicyException): a prefilled PolicyException (policies.kyverno.io/v1 for CEL policies, kyverno.io/v2 for legacy ones) for the UI's YAML create flow. |
trivy.rescan {ref, useWriteContext?} | → {usedContext}. Deletes the report so the operator recreates it ("Delete report to trigger a rescan"). Only kinds the operator regenerates are accepted (VulnerabilityReport, ConfigAuditReport, ExposedSecretReport, RbacAssessmentReport, InfraAssessmentReport, SbomReport and their Cluster* equivalents); any other kind, such as ClusterComplianceReport, is bad_request. |
kubescape.scanNow {cluster, useWriteContext?} | → {usedContext, jobs}. Creates a Job from each of the operator's scan CronJobs. |
hubble.status {cluster} | → HubbleStatus: relay location, available, error, ServerStatus (numFlows, maxFlows, seenFlows, flowsPerSec, uptime) and the per-node state. |
hubble.serviceMap {cluster, namespace, windowSec?} | → {nodes, edges, truncated?}: workloads (identity-aggregated) and edges with requests, errors, drops over the window (default 300 s, max 3600), built from a short filtered stream. |
hubble.drops {clusters?, windowSec?} | → {groups, errors, windowSec}: dropped flows grouped by (src workload, dst workload, reason) with count, lastSeen and the likely policies (NetworkPolicy / CiliumNetworkPolicy). |
settings.get | → the settings document. |
settings.set {patch} | → the merged document. patch is an RFC 7386 JSON merge patch (null deletes a key, arrays replace). |
search {text, limit, ipPerKind?} | → {results: [{cluster, gvr, kind, namespace, name}], ip?} over every kind currently watched on the selected clusters: case-insensitive name contains, prefix matches first, at most limit (default 50, max 200). When text reads as an IP query (an address, a partial address such as 10.42., a CIDR, an a-b range, IPv6, [v6]:port, ip:port) the result also carries ip: {query, mode, groups, pending?, skipped?}: query is the normalized text, mode is addr, cidr, range or prefix, and each group ({gvr, kind, total, hits}) is one kind with its true total of matching objects across clusters and at most ipPerKind hits (default 5, max 50). A hit is {cluster, gvr, namespace?, name, field, label, value, match, detail?}; match is exact, contains (the object's CIDR or range holds the address), within, overlap or prefix. Groups are ordered by best match, then kind. Each object yields one hit. The name search still runs, so a wrong detection (v1.2) only adds an empty IP section. pending lists sources still loading ({cluster, kind?}, no kind = discovery not loaded yet): ask again shortly (the UI retries at most 5 times, 600 ms apart). skipped lists sources that could not be read (reason: forbidden, not found, budget when the cluster is at its watch limit, or error when the watch could not start for another reason). A weak query (a prefix with fewer than two complete IPv4 octets or IPv6 groups, such as 1. or 10.4) only scans the tokens of kinds that are already watched (Pods, Services, EndpointSlices, Nodes, Ingresses, Gateways) and starts no watch. A strong query (an address, CIDR or range, or a prefix with two or more complete parts) also starts the on-demand IP sources the cluster serves (ServiceCIDR, MetalLB IPAddressPool and BGPPeer, Multus NetworkAttachmentDefinition, CiliumLoadBalancerIPPool, CiliumPodIPPool, CiliumNode, Calico IPPool) and waits up to 800 ms for them to list; they then linger like any on-demand watch. A source that is still listing shows up in pending; one that cannot start because the watch budget is full is in skipped with reason: "budget". |
ref is {cluster, gvr, namespace?, name?, uid?}; gvr is v1/pods or apps/v1/deployments. In create mode ref.name may be empty.
Pinning a request to an object incarnation (ref.uid). A UI that read an object and acts on it later must not hit a different object that was created under the same name in between (GitOps recreates things). When uid is set: object.delete sends Preconditions{UID} (the API server refuses a mismatch); object.action (including the Flux actions) and update-mode object.apply first read the live object and fail with code conflict and the message object was replaced when its uid differs, before anything is patched (apply also sends the uid in the PUT); stream.open with a ref (logs, exec, debug, port-forward) checks it before routing. jobs.start takes no object refs. Without uid nothing changes.
Mutations: contexts and idempotency
- Secrets are masked unless
reveal: true.object.get,object.subscribeand theliveobject of a conflict replace every Secretdata/stringDatavalue with"__v8s_masked__"(keys kept) and stripkubectl.kubernetes.io/last-applied-configuration. An update (object.applyorobject.dryRuninupdatemode) that still contains the sentinel for a key keeps that key's live value, and a stripped last-applied annotation is kept; a sentinel for a key that does not exist isbad_request. - Every mutating request carries a client
requestId(object.apply,object.delete,object.action). The agent remembers the outcome (result or error) for 10 minutes; a repeat, even while the first is still running, returns that outcome without acting twice. A mutation runs under a 60 s timeout that does not follow the caller: a connection that drops mid-request neither aborts it nor drops its dedupe entry, so a retry after a reconnect replays the recorded outcome (waiters stop only when their own request ends). Dry runs are not deduplicated. - Reads and watches always use the read context. For a mutation the agent asks
SelfSubjectAccessReviewon the read context (cached 60 s). If allowed, it runs there (a 403 from the read context's own call, after an allowed review, is the server's answer:forbidden). If denied and the cluster has a linked write context (settings.links) andautoSwitchWriteis on (default), it runs through the write context. If auto-switch is off, the error iswrite_confirm: the UI asks the user and retries withuseWriteContext: true, which runs the request through the write context (honoured only when a link exists; without one the error isforbidden). Streams, jobs and dry runs take the same flag. Before the first routed write the agent compares thekube-systemnamespace uid of both contexts (cached); a mismatch islink_mismatchand nothing is written. A 401 from the write context, or a 403 for which the write context's own access review also denies or fails, iswrite_unavailablewith the server's message; any other rejection through the write context (admission, quota, PodSecurity, validation) keeps its own code (forbidden/invalid) and message. If the review itself fails, the read context is tried and the server decides. Results carryusedContext.access.checkfollows the same rule: with auto-switch off, a check that only the write context allows is{allowed: false, needsConfirm: true}. - Linked contexts are listed in
clusters.listaswriteContextof the read cluster, and are not listed as clusters of their own.
Settings document
{groups: {name: [clusterId]}, links: {clusterId: writeContextId}, autoSwitchWrite: bool (default true), stars: [gvr], bookmarks: [{name, url}], selection: [clusterId], columnLayouts: {gvr: {...}}, problemPrefs: {}, acks: {}, nodeShell: {clusterId | "*": {image?, namespace?, priorityClass?}}, portForwards: [{name?, ref, port}]}. Desktop persists it atomically (temp file + rename, mode 0600) to os.UserConfigDir()/v8s/settings.json; a corrupt file does not stop startup: it is renamed to settings.json.corrupt-<unix> and defaults are used; fake mode keeps it in memory unless --settings is given.
Streams
Logs, exec, debug containers, node shells and port-forwards each get their own WebSocket, GET /stream, so a chatty log never delays view patches or keystrokes (performance.md §8).
- The client sends
stream.open {type, …}on the data socket. The agent validates the request, routes it likeobject.action(read context when allowed, else the linked write context;write_confirm/useWriteContextas in Mutations) and answers{streamId, usedContext}. A denied stream fails here. - The client opens
GET /streamwithSec-WebSocket-Protocol: v8s.v1, token.<hex>, stream.<streamId>(same token andOriginrules as/ws; the id never appears in a URL). The id is single use and valid for 30 s; the agent echoesv8s.v1.
type | Params | Notes |
|---|---|---|
logs | ref (a pod, with container?; or a workload / service, whose pods come from spec.selector) or selector: {cluster, namespace, labelSelector}; follow, tailLines (default 1000), sinceSeconds, previous, timestamps, download | One container: raw lines. Several (at most 50 containers, a snapshot of the started pods when the stream opens): merged by timestamp in the agent, every line prefixed <pod>/<container>\t. |
exec | ref (pod), container?, command?, tty? (default true) | No command: shell discovery /bin/bash → /bin/sh → /busybox/sh (an attempt that fails because the binary does not exist, before any output, moves on). Uses the WebSocket executor (v5.channel.k8s.io) with SPDY fallback. |
debug | ref (pod), target (container), image | Adds an ephemeral container (pods/ephemeralcontainers), waits for it, execs a shell in it. |
nodeshell | node (+ cluster) | See operations.md. Image, namespace and priority class come from settings.nodeShell ("*" or the cluster id); the default image is a busybox pinned by digest, the namespace v8s-system (created with pod-security.kubernetes.io/enforce: privileged). The first session attaches to the pod's TTY; further sessions on the same node exec nsenter … in it. Pods are deleted when the attached session ends, expire after activeDeadlineSeconds: 3600, and expired v8s-node-shell-* pods are collected on the next use of the context. |
flows | flows: {cluster, scope: {namespace?, workload?, pod?}, filter: {verdict?, dropReason?, protocol?, httpStatus?, dnsQuery?, direction?}} | Hubble flows (integrations.md). The agent reaches hubble-relay through a port-forward with the cluster's credentials and always sends the scope and filter to the relay as a server-side FlowFilter; a scope without a namespace, workload or pod (an unscoped follow) is refused with bad_request. Agent → client text frames (JSON FlowsFrame): {"ready": {usedContext}}, then batches {"flows": [...], "rate": {shown, total, sampled}} at most every 100 ms and at most ~200 flows/s (above that the agent samples and reports the observed total), and {"end": true, "error"?}. Client → agent: {"pause": true} / {"resume": true}; a stream paused for 10 s is cancelled. |
portforward | ref (pod or service), port | Desktop and v8s serve only. Binds 127.0.0.1:<free port>; no socket: the result carries localPort and forwardId. A service resolves to a ready backing pod (its targetPort mapped) and re-resolves, rebinding the same local port, if the pod dies. portforward.list / portforward.stop manage them; saved forwards live in settings.portForwards. |
Logs frames. Agent → client: binary frames of UTF-8 lines, batched at most 100 ms or 64 KiB. Credit-based flow control: the stream starts with 256 KiB of credit; the client adds more with the text frame {"credit": n} (bytes). The agent deducts every frame (it may overshoot by one frame) and stops sending, and so stops reading the API server's stream, while the balance is not positive. The stream ends with {"end": true, "error"?}. With download: true no socket is opened: the result carries downloadUrl (/stream/download?streamId=…), a single use GET (the id is the one-shot token; the Origin allowlist applies) that returns the whole log, merged the same way, as one text/plain response streamed straight from the agent.
Interactive frames (exec, debug, node shell). Client → agent: binary [0x00][stdin bytes]; text {"resize": {"cols", "rows"}}. Agent → client: binary [0x01][stdout], [0x02][stderr] (a TTY merges them into stdout); text {"ready": {usedContext, shell?, container?, pod?, attached?}} first, and last {"exit": code, "error"?} before the close.
Limits. A stream that runs through a write context has a 15-minute idle timeout (any traffic in either direction resets it) and a 60-minute cap; the exit/end frame says which. Streams on the read context have none on desktop. A forward through a write context has the 60-minute cap only.
Jobs
jobs.start {requestId, type, params} runs a long operation as an agent-owned job and answers {jobId} (a repeated requestId returns the same job for 10 minutes). Any denied, unroutable or invalid request fails the call itself, before a job exists. Every change of a job is pushed to every connected data socket as a Job frame ({jobId, type, state: running|done|failed|cancelled, cluster?, subject?, startedAt, endedAt?, progress: [{at, message, item?, state?}], progressDropped?, error?, usedContext?}; progress holds the last 200 entries); jobs.list returns the same states for a reconnecting client, and jobs.cancel {jobId} stops one.
type | params | Behaviour |
|---|---|---|
drain | {cluster, node, options: {ignoreDaemonSets (default true), deleteEmptyDirData, force, gracePeriodSeconds, timeoutSeconds (default 300), podSelector, disableEviction}} | kubectl's drain logic (k8s.io/kubectl/pkg/drain): cordon, then evict through the Eviction API, retrying every 5 s while a PDB refuses (progress state waiting-pdb). disableEviction deletes instead of evicting (PDBs are not honoured). Pods without a controller need force, pods with emptyDir data need deleteEmptyDirData, else the job fails before evicting anything. Cancel, failure or a dead agent leave the node cordoned; re-running resumes. Routed through the write context when patch nodes is denied. |
helm.rollback | {cluster, namespace, name, revision, wait, timeout, cleanupOnFail, forceReplace, force} | Helm 4 SDK action.Rollback as the user. |
helm.uninstall | {cluster, namespace, name, keepHistory, wait, timeout, cascade, force} | action.Uninstall. |
helm.retry | {cluster, namespace, name, markFailed, wait, timeout, force} | Re-runs the last upgrade from the stored chart and values; a stuck pending-* release needs markFailed first. |
A Helm action on a release carrying the labels helm.toolkit.fluxcd.io/name and /namespace fails the jobs.start call with gitops_managed (and a hint: use Flux reconcile / force / reset) unless force: true. (forceReplace is Helm's own --force.) Helm 4 reads and rolls back releases written by Helm 3 (same storage format; verified by test).
Lifetime. Jobs survive client disconnects. When the last data socket closes, running jobs continue for at most 15 minutes, then they are cancelled (a drain stays cordoned); a client connecting again cancels the countdown. State is in memory only.
Resource kinds
Every kind goes through the same engine; a module per kind supplies GVR, columns, projection, sort/filter accessors and tone. View queries use the module's column keys for sort and filters (eq/in on any string, dictionary or integer column, contains on any string column; tone columns filter by tone number). A Column has key, type, label, width (px hint) and align. The default sort is statusTone severity then name, except events (lastSeen descending).
Curated (mode A: protobuf, typed, projected before the cache). Columns after cluster, name and namespace (cluster-scoped kinds have no namespace column); all end with statusTone where meaningful and createdAt (age):
| GVR | Columns |
|---|---|
v1/pods | ready, containers, status, restarts, node |
apps/v1/deployments | ready, upToDate, available, images |
apps/v1/statefulsets | ready, images |
apps/v1/daemonsets | desired, current, ready, upToDate, available, images |
apps/v1/replicasets | desired, current, ready, owner |
batch/v1/jobs | completions, duration, status, owner |
batch/v1/cronjobs | schedule, suspend, active, lastSchedule |
v1/services | type, clusterIP, externalIP, ports, selector |
networking.k8s.io/v1/ingresses | class, hosts, address, ports |
v1/nodes | status, roles, version, internalIP, os, kernel, runtime, cpu, memory, pods, taints |
v1/namespaces | status |
v1/persistentvolumeclaims | status, volume, capacity, accessModes, storageClass |
v1/persistentvolumes | status, claim, capacity, accessModes, reclaimPolicy, storageClass |
v1/events | type, reason, object, message, count, lastSeen, source (source.component, else reportingController). Warning events only (fieldSelector=type=Warning); a query with involved lists all events of one object (Events of one object). |
autoscaling/v2/horizontalpodautoscalers | reference, targets, minPods, maxPods, replicas |
policy/v1/poddisruptionbudgets | minAvailable, maxUnavailable, allowed, healthy, expected |
networking.k8s.io/v1/networkpolicies | podSelector, policyTypes, ingress, egress |
v1/serviceaccounts | secrets |
discovery.k8s.io/v1/endpointslices | service, addressType, ready, total |
Generic (mode C: server-side Table). Every other listable kind, including CRDs, ConfigMaps, Secrets and RBAC kinds, is watched with Accept: application/json;as=Table;v=v1;g=meta.k8s.io and includeObject=Metadata, so no object body (and no Secret value) reaches the agent. Columns: cluster, name, namespace (if namespaced), the printer columns with priority 0 (typed from columnDefinitions: integer/number → int, date → time, boolean → dict, everything else → str), statusTone when a Ready/Status/Synced/Healthy/Available/State/Phase column exists (True, Running, 2/2 → success; False, Failed → danger; Unknown, Pending, 1/2 → warning), and createdAt. Column keys are the lower-cased name without punctuation (Created At → createdat; reserved keys get a _ suffix). date printer columns arrive from the API server as human durations (5d3h); the agent converts them to a timestamp rounded to the minute. A kind's schema is fixed by the first cluster that reports it; other clusters' tables are mapped by column name.
Kyverno, Trivy Operator, Kubescape (curated, started when discovery lists them). Kyverno policies (policies.kyverno.io/v1: ValidatingPolicy, NamespacedValidatingPolicy, ImageValidatingPolicy, MutatingPolicy, GeneratingPolicy, DeletingPolicy and their Namespaced* variants, PolicyException; legacy kyverno.io/v1 ClusterPolicy / Policy flagged read-only) are mode B with columns mode (Audit | Enforce | Mixed, from validationActions or per-rule failureAction), readOnly, ready, rules, background, severity, message. Reports are mode C (server-side Table, counts only): wgpolicyk8s.io/v1alpha2 PolicyReport / ClusterPolicyReport and openreports.io/v1alpha1 Report / ClusterReport when served, columns scopeKind, scopeName, pass, fail, warn, error, skip. Trivy aquasecurity.github.io/v1alpha1 VulnerabilityReport, ConfigAuditReport and ExposedSecretReport are curated Table modules with kind, workload, container (from the trivy-operator.resource.* / trivy-operator.container.name labels), repository, tag, scanner, critical, high, medium, low, unknown (RbacAssessment, InfraAssessment, the Cluster* variants and ClusterComplianceReport are watched only while their problem class is enabled). Kubescape summary kinds of spdx.softwarecomposition.kubescape.io (VulnerabilityManifestSummary, WorkloadConfigurationScanSummary) are read as typed partial JSON, with a paged list every 5 minutes when watch is unsupported.
Flux (mode B, typed partial JSON; curated, always watched once discovery shows them). source.toolkit.fluxcd.io GitRepository, OCIRepository, HelmRepository, HelmChart, Bucket (v1), kustomize.toolkit.fluxcd.io/v1 Kustomization and helm.toolkit.fluxcd.io/v2 HelmRelease, at whichever version the cluster serves; notification and image kinds stay generic. Columns after cluster, name, namespace: ready (True / False · Reason), suspended, revision, source, interval, lastReconcile, message, requestedAt, lastHandled, dependsOn, statusTone, createdAt.
Problems view
view.subscribe with gvr: "v8s/v1/problems" (protocol.ProblemsGVR) serves the problems engine through the ordinary view engine, per cluster, with the same windowing, patches and cross-cluster merge as a resource list. Columns after cluster, name (the subject's name), namespace: severity (critical | error | warning | info), severityRank (0 critical … 3 info), class, family, kind, title, message, since (from the evidence), lastChanged (last change of severity, count or message), count, source (trivy | kubescape | kyverno | hubble), acked ("true" | "false"), problemId (the stable problem id used by problems.evidence, problems.ack, and problems.unack), statusTone. Filters: family in, class in, severity in, cluster, namespace (the query's namespaces), text (subject name), acked eq. Default sort severityRank, lastChanged desc, name; since is sortable for the "oldest first" order. Grouping by family, class, cluster or namespace is done by filters (the UI groups). The problemId cell is the problem's stable id, hash(cluster, class, group/kind, namespace, name, discriminator), so a Deployment recreated by GitOps keeps its problem and its acknowledgement. (Wire row ids stay per-subscription like every view.)
The engine runs per agent instance and cluster over the tier-0 stores: a watch event marks its key dirty (plus the keys that join to it: EndpointSlice → Service → Ingresses, ReplicaSet → pods, Job → CronJob) and a pass every 250 ms re-evaluates only those keys; time-based conditions (Pending > 5 min, OOMKilled within 1 h) are woken by a deadline heap; a raised problem is held 30 s after its condition clears (hysteresis) and cleared at once when its object is deleted. Pod problems of one class in one workload roll up to a single row (Deployment api: 2/3 pods CrashLoopBackOff, the pods are count and evidence). Classes are switched with settings.problemPrefs = {classes: {class: bool}, clusters: {clusterId: {class: bool}}} (per-cluster wins over global over the class default); disabled classes are not evaluated and their problems are removed in the agent. cluster.unreachable is raised from the cluster state (unreachable, reconnecting, auth-required).
Helm releases (gvr: "helm.sh/v1/releases", virtual). Built from Secrets with label owner=helm watched metadata-only; one row per release (its latest revision, stable id). Columns after cluster, name, namespace: revision, status, updated, managedBy (flux:<ns>/<name>), statusTone. Nothing is decoded for the list.
Watch lifecycle
- Tier 0 starts when a cluster is selected and runs until it is deselected: pods, nodes, namespaces, deployments, statefulsets, daemonsets, replicasets, jobs, cronjobs, services, endpointslices, ingresses, persistentvolumeclaims, Warning events, plus metadata-only watches of CustomResourceDefinitions and APIServices that invalidate discovery.
- Any other kind is watched on demand: view subscriptions hold references, one watch per (cluster, kind) however many views or clusters-in-scope use it. When the last reference goes, the watch lingers 5 minutes; each cluster has a budget of 96 watches, and a new watch beyond it evicts the least recently used lingering one (tier-0 and referenced watches are never evicted; if nothing can be evicted the kind simply shows no rows from that cluster).
- Object events: an events view with
involvedholds a per-object events watch (keyv8s/v1/objectevents|<events namespace>|<Kind>|<namespace>|<name>) with the same reference counting, but a 30 s linger. It counts against the 96-watch budget and is LRU-evictable while lingering; a watch that fails (forbidden, timeout) is discarded at once instead of retrying during the linger. - Discovery (aggregated discovery with legacy fallback) is cached per cluster, refreshed every 5 minutes and when a CRD or APIService changes.
- Rows appear progressively while a kind syncs: projected list pages and initial watch events are shown provisionally and reconciled by the reflector's final
Replace. Fallback LISTs are paged (500).
Hosted (v8s server)
The self-hosted multi-user mode speaks the same protocol over the same /ws and /stream; only authentication and the engine behind the socket differ. Design: auth.md, performance.md §10, packaging.md.
Connection auth
/wsand/streamauthenticate by the session cookie__Host-v8s_session(HttpOnly, Secure, SameSite=Strict, Path=/), not the token subprotocol. The client still offersSec-WebSocket-Protocol: v8s.v1(400 without it); there is notoken.*entry.- Strict origin:
Originmust equal the configured public URL; missing or different is 403. Chromium sends noSec-Fetch-*headers on WebSocket handshakes (Firefox and WebKit do), soSec-Fetch-Siteis checked only when present (then it must besame-origin). A page cannot forgeOrigin, which is what blocks cross-site WebSocket hijacking. No cookie, or an expired/ended session, is 401: the UI sends the browser to/auth/login?return=<path>. Ending a session (logout, expiry, eviction) closes its sockets. GET /stream/downloadneeds the cookie and the single-usestreamId; a presentSec-Fetch-Sitemust besame-origin(WebKit sends none on a programmatic<a download>, the Safari and iOS path). Every state-changing HTTP request (POST /auth/logout) must carry a matchingOrigin, orSec-Fetch-Site: same-originwhenOriginis absent; a foreign value is 403.GET /api/merejects cross-site fetches.Hello.modeis"hosted".
Engines
Each identity (IdP subject + group set) has its own engine (cluster manager, views, problems, ops, streams, jobs, settings) whose cluster source is the server's cluster list filtered to the user's IdP groups (adminGroups see all; a cluster with groups: ["*"] is visible to every signed-in user). clusters.list returns only those clusters; clusters.select of any other id fails with unknown cluster. Access to a cluster is checked only when it is selected.
- The engine starts with the identity's first client and stops its watches 30 s after the last client closes (a reconnect within the grace keeps them). Running jobs keep the engine record, without watches, until they end; the jobs manager's 15-minute no-client bound still applies.
- Several sessions of one identity share one engine; the cluster token used is the live session's token that lives longest.
- Settings are the same document as desktop, persisted per user as JSON under
dataDir/users/. - Port-forward is disabled (
stream.opentypeportforwardfails): a local port is meaningless on a server. HTTP preview (operations.md) is not implemented yet. - Kiosk clusters are read-only: mutations, exec/attach, logs, drain and Helm are unavailable, and access reviews answer "no" for writes.
- Requests carry
User-Agent: v8s/<version> (corr <hmac>). Read QPS is 20 (burst 40) per (user, cluster) with a 100 (burst 200) ceiling per cluster across users.
HTTP endpoints
| Endpoint | Purpose |
|---|---|
GET /auth/login?return=/path | start OIDC login (code + PKCE S256 + state + nonce; state/nonce/verifier stored server-side, bound to the browser by a short-lived __Host-v8s_flow cookie) |
GET /auth/callback | verify the ID token (issuer, audience, nonce, expiry, JWKS signature), create the session, start the cluster-app flow |
GET /auth/cluster-login?return= | re-run only the cluster-app flow (clusters auth-required); silent (prompt=none) first, interactive on login_required |
GET /auth/cluster-callback | store the cluster app's ID token and refresh token in the session (memory only) |
POST /auth/logout | delete the session and its tokens, clear the cookie (204) |
GET /api/me | {username, sub, groups, expiresAt, admin, clusterAuth: "ok"|"required"}; 401 without a session |
GET /healthz, GET /readyz | liveness; readiness (identity provider reachable) |
The flows finish with a small HTML page that navigates client-side to return (a 302 from a redirect chain that began at the IdP is cross-site and would not carry the Strict cookie).
Fake mode
--fake clusters=N,pods=P,churn=R[,rbac=1][,lograte=L] serves, per cluster: P/N pods owned by one ReplicaSet per app (400 apps, each with a Deployment, a current and a previous ReplicaSet for rollback, a Service and an EndpointSlice), StatefulSets, DaemonSets, Ingresses, 150 nodes, 37 namespaces, Warning events for failing pods, Normal events (Scheduled for pods, ScalingReplicaSet for Deployments, Starting / RegisteredNode / NodeNotReady for nodes, all with a source; node events live in default), Jobs and CronJobs, ConfigMaps and Secrets (Table mode), storageclasses, the seven Flux CRDs with about 30 Flux objects in varied states (a requested reconcile is handled about a second later, setting status.lastHandledReconcileAt), and Helm release Secrets (gzip+base64 payloads; podinfo with three revisions, a broken-release that failed, one stuck pending, one Flux-managed). Pod logs are synthetic lines (lograte lines per second per pod, default 20), exec is an echo shell, port-forward serves a small HTTP page, and drain runs over a demo pod set on node-3 (a PDB refuses its pods twice, plus DaemonSet, emptyDir, unmanaged and finished pods) and node-4..node-8. Helm actions in fake mode only change release records. Object get, subscribe, dry run, apply, delete and actions work against an in-memory store that feeds the views (a successful apply bumps resourceVersion; scaling a Deployment records a live ScalingReplicaSet event). Fake pods, nodes, services, EndpointSlices and ingresses carry IPs: pod 10.64.0.0 + node*512 + 2 + n inside each node's /23 pod CIDR, node 10.0.x.y (the first three also have an external IP), Service 10.96.x.y, a MetalLB LoadBalancer ingress-nginx/ingress-nginx-controller on 192.168.100.10, a team-2/legacy-lb that only requests 192.168.100.250, a dual-stack team-0/dual, and a Multus secondary address on a few pods. IP-only CRD objects (served as mode B kinds): a ServiceCIDR, MetalLB pools public (192.168.100.0/24) and reserved, a BGPPeer, four NetworkAttachmentDefinitions (team-1/macvlan-conf host-local, team-2/whereabouts-net, team-3/static-net, team-4/sriov-net dual-stack) on every cluster, a Cilium LoadBalancer pool and one CiliumNode per node on even-index clusters, and a Calico IPPool on odd-index clusters. The fake honours list and watch field selectors (type=Warning, involvedObject.*, metadata.name) and namespaced events lists like a real API server, so the tier-0 events watch stays Warning-only. G3 adds fixtures for the problems engine: failing pods of every kind from the pod generator, Deployments without available replicas (rollout stuck), Ingresses routing to a missing Service and to a Service without ready endpoints, a pending PVC with its provisioning Warning event, a failed bare Job and cron Jobs, NotReady and memory-pressure nodes, APIServices (one unavailable), validating and mutating webhooks with no endpoints, cert-manager Certificates (expiring, not ready), an unaccepted Gateway API HTTPRoute, Flux controllers (one down) and Flux / Helm objects in failing, stalled, hung and dependency-blocked states; Kyverno policies and reports (policy failures), Trivy reports (some images with critical vulnerabilities across clusters, an exposed secret), Kubescape summaries, and a hubble-relay Service per cluster (except staging) backed by an in-process fake relay that produces frontend / backend / DNS flows and POLICY_DENIED drops for the flows stream, the service map and the drops view. With rbac=1, the second cluster is read-only for mutations and a context <name>-admin can be linked to it (settings.links) to exercise write-context switching.
Pods view (gvr: "v1/pods")
Columns: see PodColumns. Sortable columns: every column of the schema. Filters: statusTone in [...] (tones as strings "1"…"5"), status eq <reason>, node eq <name>. namespaces restricts by namespace; text is a case-insensitive substring match on name; IP-like text (see search) also matches objects that hold a matching address, so 10.42., 10.42.0.0/16 or 10.0.0.5 filter the list by IP (the same on Services, EndpointSlices, Nodes and Ingresses). The ip column shows the pod's IPs (comma-separated) and sorts numerically; pods without an IP sort last. Default sort: statusTone severity (danger, warning, others), then name.
Status reason follows kubectl get pods (including native sidecars: restartable init containers count in ready/containers, and SchedulingGated): a container's waiting/terminated reason wins (CrashLoopBackOff, ImagePullBackOff, OOMKilled, Error, ContainerCreating), then Terminating if deleting, else the pod phase. Tone: danger for crash/pull/OOM/Error/Failed, warning for Pending/ContainerCreating/Terminating/not-ready Running, success for ready Running, info for Succeeded/Completed.