A proxied KVM may be framed by the console that proxies it

frame-ancestors 'none' forbids framing even from the same origin, so /kvm/ paths say
'self' instead. Without this the iframe was refused before it loaded.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

PLAN.md

@@ -293,10 +293,16 @@ something long in one, switch away and back, refresh — it's all still there.
   carries the rule it was taken under. The page **detects the existing cron job**
   (zfSnap, zfs-auto-snapshot, sanoid, or a bare `zfs snapshot`) and says so, warning if a Ham
   Lab schedule is running as well.
-  **Nothing is destroyed unseen.** Every schedule answers *what would it delete?* with the
+  **Nothing is destroyed unseen.** Only names that parse as a stamp and a TTL are ever
-  list, sizes and dates, before Run now touches anything; only names that parse as a stamp
+  candidates for expiry, so a snapshot taken by hand is invisible to a schedule; Run now
-  and a TTL are candidates, so a snapshot taken by hand is invisible to it; and a snapshot
+  says that expired snapshots go with it; and a snapshot deleted by hand is confirmed first
-  deleted by hand needs its full name typed back.
+  and needs its full name echoed back by the caller. (A "what would it delete?" preview
+  shipped and was removed the same day as redundant — Mitchell's call.)
+  The datasets table is a **snapshot explorer**: each dataset shows how many snapshots it has
+  and what they cost, and opens into the snapshots themselves — when each was taken, **when
+  it expires** (read from the TTL in its own name, so no server call), its size, and Delete.
+  Deleting takes the same-named snapshot on descendant datasets too, which is how a recursive
+  schedule made it.
   **A schedule is a real cron job** (2026-09-24, Mitchell's call after the first cut ran it
   from a ticker inside the daemon). Ham Lab writes `/etc/cron.d/hamlab-zfs`, owns it, and
   rewrites it whole on every change; each line calls `hamlab zfs-snapshot <id>` as the
@@ -503,11 +509,12 @@ something long in one, switch away and back, refresh — it's all still there.
 
 ## To do
 
-- **Deprecate copyparty** — asked for 2026-09-23, not started. `copyparty` on `grid`
+- **Grow the Files tab until copyparty can go** — asked for 2026-09-23 as two items (Files
-  (`copyparty.service`, `:3923`, `/etc/copyparty.conf`, serving all of `/tank` as user
+  polish, and deprecating copyparty), merged 2026-09-24: they are the same tab and the same
-  `core` with one account behind NPM) overlaps the **Files** tab almost entirely. The aim
+  work. `copyparty` on `grid` (`copyparty.service`, `:3923`, `/etc/copyparty.conf`, serving
-  is to stop the service and keep only Ham Lab. What Files must gain first, in the order
+  all of `/tank` as user `core` with one account behind NPM) overlaps **Files** almost
-  that matters:
+  entirely. The aim is to stop the service and keep only Ham Lab, with general ease-of-use
+  polish along the way. What Files must gain first, in the order that matters:
   - **Multi-select and bulk actions.** copyparty selects many rows and moves, deletes or
     downloads them together; Files acts on one row at a time.
   - **Download a folder**, and a multi-file download, as a streamed zip or tar — the thing
@@ -527,26 +534,44 @@ something long in one, switch away and back, refresh — it's all still there.
     `hamlet`'s `docs/hosts.md` bare-metal list, `docs/gotchas.md` (the "`docker ps` is not
     the inventory" note names it) and the `grid` row in `CLAUDE.md`.
 
-- **Deprecate Dockhand** — asked for 2026-09-23, not started; the *homelab* half of this
+- **Grow the Docker tab until Dockhand can go** — asked for 2026-09-23 and widened
-  (migrating every stack off Dockhand's data dir, then removing the container) is
+  2026-09-24 to take in Docker tab polish and feature work, on the same reasoning as the
-  `hamlet`'s `docs/pending.md` → "Retire Dockhand; Ham Lab becomes the orchestrator",
+  Files item: it is one tab, and the gaps that block retiring the old tool and the things
-  agreed 2026-09-20. This entry is the *app* half only: what Ham Lab must do before that
+  that would simply make it better are the same body of work. The *homelab* half —
-  migration can start. Its Stacks page already creates, edits, deploys, updates, restarts,
+  migrating every stack off Dockhand's data dir, then removing the container — is `hamlet`'s
-  stops, downs and deletes stacks on every machine, so the gaps are Dockhand's extras:
+  `docs/pending.md` → "Retire Dockhand; Ham Lab becomes the orchestrator", agreed
-  - **Git-sourced stacks.** Dockhand's `stack_sources` table points a stack at a repo and
+  2026-09-20. This entry is the *app* half.
-    pulls it. Ham Lab has no equivalent. Decide whether to build it or to drop it — most
+  Where it stands: Stacks already creates, edits, deploys, updates, restarts, stops, downs
-    stacks here have no row in that table anyway, so dropping it may be honest.
+  and deletes stacks on every machine, and Containers does start/stop/restart, logs that
-  - **Scheduled image updates.** Ham Lab checks for new images only when asked (a registry
+  follow, inspect, and the images/volumes/networks tables. So this is not a rewrite.
-    request Docker Hub counts) and never updates by itself. If anything relies on Dockhand
+  - **What Dockhand still does that Ham Lab does not.**
-    updating on a schedule, that must move here or be dropped on purpose.
+    - *Git-sourced stacks.* Dockhand's `stack_sources` table points a stack at a repo and
-  - **Webhooks / per-host environments**, if either is in use — inventory before deciding.
+      pulls it. Ham Lab has no equivalent. Decide whether to build it or drop it — most
-  - **Deploying from a host path without an orchestrator container.** Ham Lab already runs
+      stacks here have no row in that table anyway, so dropping it may be the honest answer.
-    compose inside `dockhand` because that is how the stacks were deployed; once they move
+    - *Scheduled image updates.* Ham Lab checks for new images only when asked, since each
-    to a neutral home the "via" path is unused for them, but a stack deployed to `grid` or
+      check is a registry request Docker Hub counts, and never updates by itself. If
-    the Mac still goes over `tcp://<node>:2375` from the hub. Decide whether Ham Lab should
+      anything relies on Dockhand updating on a schedule, that must move here or be dropped
-    instead ask the node's own Ham Lab to deploy locally, which would end the `*:2375`
+      on purpose. Note the Jobs tab and the ZFS schedules already show the shape this would
-    exposure (its own item in `docs/pending.md`).
+      take: a cron line Ham Lab owns, not a ticker in the daemon.
-  - *Not app work, but the trigger:* nothing here blocks starting the migration except the
+    - *Webhooks and per-host environments*, if either is in use. Inventory before deciding.
+  - **Known gaps in the tab itself**, worth closing whether or not Dockhand goes:
+    - *Removing networks* — volumes and images can be pruned and removed, networks cannot.
+    - *Container detail is thin next to the stack view.* No per-container resource limits,
+      restart-policy editing, or exec-into-container from the tab (the Terminal tab is the
+      workaround). Decide which of these belong here at all.
+    - *Logs are polled with `--since` rather than followed over a held connection.* That was
+      deliberate and works, but a long tail is choppier than the Services tab's live tail,
+      which does hold a connection. Worth reconciling the two.
+    - *Image update checks are remembered six hours and asked for per stack*, so there is no
+      one view of "what is out of date across the fleet".
+  - **The `*:2375` question, which this is the moment to settle.** Ham Lab runs compose
+    inside `dockhand` because that is how the stacks were deployed; once they move to a
+    neutral home that path is unused for them, but a stack deployed to `grid` or the Mac
+    still goes over `tcp://<node>:2375` from the hub. Decide whether the hub should instead
+    ask the node's own Ham Lab to deploy locally, which would end the unauthenticated
+    Docker socket exposure — its own item in `docs/pending.md`, currently filed under
+    "decided, no action", and this is the change that would make closing it free.
+  - *Not app work, but the trigger:* nothing above blocks starting the migration except the
     inventory. Do that first.
 
 - **A Virtualization tab** — asked for 2026-09-23, not started, and **large**. Run and
@@ -560,11 +585,6 @@ something long in one, switch away and back, refresh — it's all still there.
   `internal/term`); snapshots and clones; and what it does on a host with no virtualisation
   at all, which is every host here today. Worth scoping as its own plan before starting.
 
-- **Files explorer: cleanup and ease of use** — asked for 2026-09-23, not started.
-  General polish and ease of use. The **Deprecate copyparty**
-  item names the heavier pieces (multi-select and bulk actions, folder download, resumable
-  uploads, a gallery, search) — worth doing the two together, since they are the same tab.
-
 - **A KVM tab** — asked for 2026-09-24, not started. **Dead simple is the brief**: paste one
   HTTP link, the tab shows whatever UI that KVM serves, and the keyboard goes to it. **This
   is KVM the keyboard-video-mouse switch, not KVM the hypervisor** — the Virtualization item

internal/api/kvm.go

@@ -0,0 +1,272 @@
+package api
+
+// IP-KVMs: a device's own web page, shown inside Ham Lab.
+//
+// The whole difficulty is that Ham Lab is served over TLS and a KVM usually is not, so a
+// browser refuses to put the device's page in an iframe — mixed content, blocked before
+// anything loads. The fix is to serve the device from Ham Lab's own origin, which also
+// means it inherits Ham Lab's login instead of needing a second one, and makes the iframe
+// same-origin.
+//
+// Proxying an arbitrary web app under a path prefix is the hard part, and nothing here
+// knows anything about any particular device. A device UI asks for its assets by absolute
+// path — "/assets/app.js", "/api/whatever" — which a prefix cannot rewrite away. So the
+// prefix is only the entry point: any request Ham Lab does not serve itself is routed to
+// whichever KVM the asking page belongs to, worked out from the Referer, and from a cookie
+// when there is no Referer (a WebSocket upgrade, say). Ham Lab's own routes always win, so
+// a device can never shadow the console.
+
+import (
+	"crypto/rand"
+	"encoding/hex"
+	"encoding/json"
+	"errors"
+	"io"
+	"log"
+	"net/http"
+	"net/http/httputil"
+	"net/url"
+	"strings"
+	"sync"
+	"time"
+
+	"hamlab/internal/config"
+)
+
+const kvmPrefix = "/kvm/"
+const kvmCookie = "hamlab_kvm"
+
+type kvmProxies struct {
+	mu sync.Mutex
+	m  map[string]*httputil.ReverseProxy
+}
+
+func (s *Server) kvm(id string) (config.KVM, bool) {
+	var found config.KVM
+	ok := false
+	s.cfg.View(func(c *config.Config) {
+		for _, k := range c.KVMs {
+			if k.ID == id {
+				found, ok = k, true
+			}
+		}
+	})
+	return found, ok
+}
+
+// kvmProxy is the reverse proxy for one device, made once and kept.
+func (s *Server) kvmProxy(k config.KVM) (*httputil.ReverseProxy, error) {
+	s.kvms.mu.Lock()
+	defer s.kvms.mu.Unlock()
+	if s.kvms.m == nil {
+		s.kvms.m = map[string]*httputil.ReverseProxy{}
+	}
+	if p, ok := s.kvms.m[k.ID]; ok {
+		return p, nil
+	}
+	target, err := url.Parse(k.URL)
+	if err != nil || target.Host == "" {
+		return nil, errors.New("this KVM's address is not a URL")
+	}
+	prefix := kvmPrefix + k.ID
+	p := &httputil.ReverseProxy{
+		Director: func(r *http.Request) {
+			r.URL.Scheme, r.URL.Host = target.Scheme, target.Host
+			// Entry through the prefix keeps the path after it; anything else arrived by its
+			// own absolute path and is passed through untouched.
+			if rest, ok := strings.CutPrefix(r.URL.Path, prefix); ok {
+				if rest == "" {
+					rest = "/"
+				}
+				r.URL.Path = rest
+			}
+			r.URL.RawPath = ""
+			r.Host = target.Host
+			// The device gets its own host and none of Ham Lab's session.
+			r.Header.Del("Origin")
+			stripCookie(r, cookieName, kvmCookie)
+		},
+		FlushInterval: -1, // a video stream must not be buffered
+		ModifyResponse: func(resp *http.Response) error {
+			// The device's own framing and transport policy would stop it being embedded, or
+			// send a browser off to plain HTTP. Ham Lab is the origin now, and says what it
+			// serves; its own headers are added on the way out.
+			for _, h := range []string{"X-Frame-Options", "Content-Security-Policy", "Content-Security-Policy-Report-Only", "Strict-Transport-Security", "Referrer-Policy"} {
+				resp.Header.Del(h)
+			}
+			// A redirect to the device's own root has to come back through the prefix.
+			if loc := resp.Header.Get("Location"); loc != "" {
+				if u, err := url.Parse(loc); err == nil && (u.Host == "" || u.Host == target.Host) && strings.HasPrefix(u.Path, "/") && !strings.HasPrefix(u.Path, prefix) {
+					u.Scheme, u.Host = "", ""
+					u.Path = prefix + u.Path
+					resp.Header.Set("Location", u.String())
+				}
+			}
+			return nil
+		},
+		ErrorHandler: func(w http.ResponseWriter, r *http.Request, err error) {
+			w.Header().Set("Content-Type", "application/json")
+			w.WriteHeader(http.StatusBadGateway)
+			_ = json.NewEncoder(w).Encode(map[string]string{"error": k.Name + " unreachable: " + err.Error()})
+		},
+	}
+	s.kvms.m[k.ID] = p
+	return p, nil
+}
+
+// stripCookie removes named cookies from a request, so Ham Lab's session is never handed to
+// a device and the device never sees which KVM the browser is looking at.
+func stripCookie(r *http.Request, names ...string) {
+	cs := r.Cookies()
+	kept := cs[:0]
+	for _, c := range cs {
+		drop := false
+		for _, n := range names {
+			if c.Name == n {
+				drop = true
+			}
+		}
+		if !drop {
+			kept = append(kept, c)
+		}
+	}
+	r.Header.Del("Cookie")
+	for _, c := range kept {
+		r.AddCookie(c)
+	}
+}
+
+func (s *Server) forgetKVMProxy(id string) {
+	s.kvms.mu.Lock()
+	delete(s.kvms.m, id)
+	s.kvms.mu.Unlock()
+}
+
+// serveKVM is the entry point: /kvm/<id>/… . It also drops a cookie naming the device, so
+// that requests the page makes later by absolute path can be traced back to it.
+func (s *Server) serveKVM(w http.ResponseWriter, r *http.Request) {
+	id := r.PathValue("id")
+	k, ok := s.kvm(id)
+	if !ok {
+		jsonErr(w, 404, "no such KVM")
+		return
+	}
+	p, err := s.kvmProxy(k)
+	if err != nil {
+		jsonErr(w, 400, err.Error())
+		return
+	}
+	http.SetCookie(w, &http.Cookie{Name: kvmCookie, Value: id, Path: "/", HttpOnly: true, Secure: secure(r), SameSite: http.SameSiteLaxMode})
+	p.ServeHTTP(w, r)
+}
+
+// kvmFor works out which device a request belongs to when it arrived by absolute path
+// rather than through the prefix: the Referer names the page that asked, and a cookie
+// covers what has no Referer at all. Nothing device-specific: it never has to know which
+// paths a given KVM uses.
+func (s *Server) kvmFor(r *http.Request) (config.KVM, bool) {
+	if ref := r.Header.Get("Referer"); ref != "" {
+		if u, err := url.Parse(ref); err == nil {
+			if rest, ok := strings.CutPrefix(u.Path, kvmPrefix); ok {
+				if id, _, _ := strings.Cut(rest, "/"); id != "" {
+					if k, ok := s.kvm(id); ok {
+						return k, true
+					}
+				}
+			}
+		}
+		// asked for by a page that is not a KVM: not ours to answer
+		return config.KVM{}, false
+	}
+	if c, err := r.Cookie(kvmCookie); err == nil && c.Value != "" {
+		return s.kvm(c.Value)
+	}
+	return config.KVM{}, false
+}
+
+// kvmFallback answers a request Ham Lab does not serve itself, when it came from inside a
+// KVM's page. It returns false when the request has nothing to do with a KVM, and the
+// caller carries on with its own 404.
+func (s *Server) kvmFallback(w http.ResponseWriter, r *http.Request) bool {
+	k, ok := s.kvmFor(r)
+	if !ok {
+		return false
+	}
+	p, err := s.kvmProxy(k)
+	if err != nil {
+		return false
+	}
+	p.ServeHTTP(w, r)
+	return true
+}
+
+// ---- the list ----
+
+func (s *Server) listKVMs(w http.ResponseWriter, _ *http.Request) {
+	out := []config.KVM{}
+	s.cfg.View(func(c *config.Config) { out = append(out, c.KVMs...) })
+	jsonOK(w, 200, out)
+}
+
+func (s *Server) addKVM(w http.ResponseWriter, r *http.Request) {
+	var body struct{ Name, URL, Machine string }
+	if err := json.NewDecoder(io.LimitReader(r.Body, 4096)).Decode(&body); err != nil {
+		jsonErr(w, 400, "bad request")
+		return
+	}
+	raw := strings.TrimSpace(body.URL)
+	if raw != "" && !strings.Contains(raw, "://") {
+		raw = "http://" + raw // what you would type: an address, not a scheme
+	}
+	u, err := url.Parse(raw)
+	if err != nil || (u.Scheme != "http" && u.Scheme != "https") || u.Host == "" {
+		jsonErr(w, 400, "address: http(s)://host, or just the host")
+		return
+	}
+	name := strings.TrimSpace(body.Name)
+	if name == "" {
+		name = u.Host
+	}
+	if len(name) > maxNameLen {
+		jsonErr(w, 400, "that name is too long")
+		return
+	}
+	b := make([]byte, 6)
+	if _, err := rand.Read(b); err != nil {
+		jsonErr(w, 500, err.Error())
+		return
+	}
+	k := config.KVM{ID: hex.EncodeToString(b), Name: name, URL: u.Scheme + "://" + u.Host + strings.TrimSuffix(u.Path, "/"), Machine: strings.TrimSpace(body.Machine), Added: time.Now()}
+	if err := s.cfg.Update(func(c *config.Config) { c.KVMs = append(c.KVMs, k) }); err != nil {
+		jsonErr(w, 500, err.Error())
+		return
+	}
+	log.Printf("kvm %q added (%s) by %s", k.Name, k.URL, clientIP(r))
+	jsonOK(w, 201, k)
+}
+
+func (s *Server) removeKVM(w http.ResponseWriter, r *http.Request) {
+	id := r.PathValue("id")
+	found := false
+	if err := s.cfg.Update(func(c *config.Config) {
+		kept := c.KVMs[:0]
+		for _, k := range c.KVMs {
+			if k.ID == id {
+				found = true
+				continue
+			}
+			kept = append(kept, k)
+		}
+		c.KVMs = kept
+	}); err != nil {
+		jsonErr(w, 500, err.Error())
+		return
+	}
+	if !found {
+		jsonErr(w, 404, "no such KVM")
+		return
+	}
+	s.forgetKVMProxy(id)
+	log.Printf("kvm %s removed by %s", id, clientIP(r))
+	w.WriteHeader(204)
+}

internal/api/server.go

@@ -69,6 +69,7 @@ type Server struct {
 	storage     *storage.Manager
 	space       *space.Manager
 	update      updateState
+	kvms        kvmProxies
 	fsLocal     files.FS
 	fsSudo      files.FS // nil without passwordless sudo
 	nodes       *nodes.Manager
@@ -284,7 +285,20 @@ func New(cfg *config.Config, sessions *auth.Sessions, mgr *term.Manager, col *me
 	m.HandleFunc("PUT /api/prefs/sampler", s.auth(s.putSampler))
 	m.HandleFunc("GET /api/prefs/history", s.auth(s.getHistoryWindow))
 	m.HandleFunc("PUT /api/prefs/history", s.auth(s.putHistoryWindow))
-	m.HandleFunc("/api/", func(w http.ResponseWriter, _ *http.Request) { jsonErr(w, 404, "not found") })
+	m.HandleFunc("GET /api/kvms", s.auth(s.listKVMs))
+	m.HandleFunc("POST /api/kvms", s.auth(s.addKVM))
+	m.HandleFunc("DELETE /api/kvms/{id}", s.auth(s.removeKVM))
+	m.HandleFunc("/kvm/{id}/{rest...}", s.auth(s.serveKVM))
+	m.HandleFunc("/kvm/{id}", s.auth(s.serveKVM))
+	// A path Ham Lab does not serve may still belong to a KVM's page, which asks for its
+	// own assets by absolute path. Ham Lab's own routes matched first, so this can only
+	// catch what would otherwise have been a 404.
+	m.HandleFunc("/api/", s.auth(func(w http.ResponseWriter, r *http.Request) {
+		if s.kvmFallback(w, r) {
+			return
+		}
+		jsonErr(w, 404, "not found")
+	}))
 	m.HandleFunc("/", s.static)
 	s.mux = m
 	return s
@@ -307,9 +321,16 @@ func sensorPath(p string) bool {
 func (s *Server) Handler() http.Handler {
 	return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
 		h := w.Header()
-		// The console must never be framed. An embedded widget exists to be: it is a page
+		// The console must never be framed. Two exceptions: an embedded widget exists to be
-		// that can only read sensors, and only with a read-only token in its URL.
+		// (a page that can only read sensors, and only with a read-only token in its URL),
-		if r.URL.Path != "/embed/widget" {
+		// and a proxied KVM is framed by the console itself — 'none' forbids that even from
+		// the same origin, so those paths say 'self' instead of opening up.
+		switch {
+		case r.URL.Path == "/embed/widget":
+		case strings.HasPrefix(r.URL.Path, kvmPrefix):
+			h.Set("X-Frame-Options", "SAMEORIGIN")
+			h.Set("Content-Security-Policy", "frame-ancestors 'self'")
+		default:
 			h.Set("X-Frame-Options", "DENY")
 			h.Set("Content-Security-Policy", "frame-ancestors 'none'")
 		}
@@ -355,6 +376,17 @@ func (s *Server) setCookie(w http.ResponseWriter, r *http.Request, tok string, m
 	})
 }
 
+// signedIn reports whether a request carries a live browser session, without the
+// side effects of the auth middleware.
+func (s *Server) signedIn(r *http.Request) bool {
+	c, err := r.Cookie(cookieName)
+	if err != nil {
+		return false
+	}
+	_, ok := s.sessions.Lookup(c.Value, clientKey(r))
+	return ok
+}
+
 // auth accepts the browser session cookie or a bearer API token issued to a hub.
 func (s *Server) auth(next http.HandlerFunc) http.HandlerFunc {
 	return func(w http.ResponseWriter, r *http.Request) {
@@ -2445,6 +2477,12 @@ func (s *Server) static(w http.ResponseWriter, r *http.Request) {
 			return
 		}
 	}
+	// A path with no file of ours behind it may belong to a KVM's page, which asks for its
+	// own assets by absolute path. Checked here rather than in the router because this
+	// handler is the catch-all — and gated on a session, since this handler is public.
+	if s.signedIn(r) && s.kvmFallback(w, r) {
+		return
+	}
 	// SPA fallback
 	w.Header().Set("Cache-Control", "no-cache")
 	http.ServeFileFS(w, r, s.ui, "index.html")

internal/config/config.go

@@ -61,6 +61,21 @@ type UpdateSource struct {
 	Check string `json:"check,omitempty"`
 }
 
+// KVM is an IP-KVM: a device with a web page that gives screen, keyboard and mouse access
+// to a machine, including when that machine has no OS running. Ham Lab holds the list on
+// the hub and proxies each one, because a KVM matters exactly when the machine it is
+// attached to cannot answer for itself.
+type KVM struct {
+	ID   string `json:"id"`
+	Name string `json:"name"`
+	// URL is the device's own address, as you would type it into a browser on the LAN.
+	URL string `json:"url"`
+	// Machine is which host it is attached to, for display only — it need not be a machine
+	// Ham Lab manages, and usually the point is that it is not answering.
+	Machine string    `json:"machine,omitempty"`
+	Added   time.Time `json:"added"`
+}
+
 type Config struct {
 	Listen string `json:"listen"`
 	// PasswordHash is the single login of installs before users existed. On load it becomes
@@ -70,6 +85,7 @@ type Config struct {
 	TLS          string  `json:"tls,omitempty"` // "auto" → self-signed cert in the data dir; "" → plain HTTP
 	Tokens       []Token `json:"tokens,omitempty"`
 	Nodes        []Node  `json:"nodes,omitempty"`
+	KVMs         []KVM   `json:"kvms,omitempty"`
 	// Updates: where a newer build comes from. See UpdateSource.
 	Updates UpdateSource `json:"update,omitempty"`
 

web/src/KVM.tsx

@@ -0,0 +1,153 @@
+// IP-KVMs: a device's own web page, shown inside Ham Lab.
+//
+// Paste the address, and the device appears. Nothing here knows anything about any
+// particular KVM — it is an iframe pointed at Ham Lab's own proxy, so whatever web UI the
+// device serves is what you get.
+//
+// On the keyboard: a page cannot capture keys and forward them into an iframe, and does not
+// need to. An iframe with focus receives them directly. What the browser itself swallows —
+// Escape, Tab, Ctrl-W, the function keys — is what `navigator.keyboard.lock()` releases,
+// and that needs fullscreen and only exists in Chromium. Everywhere else you get the plain
+// version, which is most keys, and the device's own on-screen buttons for the rest.
+import { FormEvent, useCallback, useEffect, useRef, useState } from 'react'
+import { KVM as Device, MachineStatus, api } from './api'
+import { Btn, Loading, askYes, toast, useEscape } from './ui'
+
+// lock() releases the keys the browser would otherwise keep for itself. Chromium only; a
+// browser without it simply does not get the extra keys.
+type KeyboardLock = { lock?: (keys?: string[]) => Promise<void>; unlock?: () => void }
+const keyboardAPI = (): KeyboardLock | undefined => (navigator as unknown as { keyboard?: KeyboardLock }).keyboard
+
+export default function KVM({ machines }: { machines: MachineStatus[] }) {
+  const [list, setList] = useState<Device[] | null>(null)
+  const [sel, setSel] = useState<string>('')
+  const [adding, setAdding] = useState(false)
+  const [err, setErr] = useState('')
+  const [full, setFull] = useState(false)
+  const box = useRef<HTMLDivElement>(null)
+  const frame = useRef<HTMLIFrameElement>(null)
+
+  const load = useCallback(async () => {
+    try { const l = await api.kvms(); setList(l); setSel((s) => (l.some((k) => k.id === s) ? s : l[0]?.id ?? '')) }
+    catch (e) { setErr(e instanceof Error ? e.message : 'failed') }
+  }, [])
+  useEffect(() => { load() }, [load])
+
+  // Fullscreen plus a keyboard lock is what makes Escape and Tab reach the machine rather
+  // than the browser. Both are undone together when fullscreen ends, however it ends.
+  useEffect(() => {
+    const onChange = () => {
+      const on = !!document.fullscreenElement
+      setFull(on)
+      if (!on) keyboardAPI()?.unlock?.()
+    }
+    document.addEventListener('fullscreenchange', onChange)
+    return () => { document.removeEventListener('fullscreenchange', onChange); keyboardAPI()?.unlock?.() }
+  }, [])
+
+  const goFullscreen = async () => {
+    try {
+      await box.current?.requestFullscreen()
+      await keyboardAPI()?.lock?.()
+      frame.current?.focus()
+    } catch (e) { toast(e instanceof Error ? e.message : 'fullscreen refused', 'err') }
+  }
+
+  const remove = async (k: Device) => {
+    if (!await askYes(`Remove ${k.name}? The device is not touched — this only forgets its address.`, 'Remove')) return
+    try { await api.removeKVM(k.id); toast(`${k.name} removed`); await load() } catch (e) { toast(e instanceof Error ? e.message : 'failed', 'err') }
+  }
+
+  if (err && !list) return <div className="dash"><div className="error">{err}</div></div>
+  if (!list) return <div className="dash"><Loading label="Reading the list…" /></div>
+
+  const cur = list.find((k) => k.id === sel)
+  const locks = !!keyboardAPI()?.lock
+
+  return (
+    <div className="kvm">
+      <div className="kvm-bar">
+        {list.length > 0 && (
+          <span className="chips">
+            {list.map((k) => (
+              <button key={k.id} className={'chip' + (k.id === sel ? ' on' : '')} onClick={() => setSel(k.id)}
+                title={`${k.url}${k.machine ? ` — attached to ${k.machine}` : ''}`}>{k.name}</button>
+            ))}
+          </span>
+        )}
+        <span className="spacer" />
+        {cur && <>
+          <span className="muted small mono kvm-url">{cur.url}</span>
+          <Btn className="btn" onClick={goFullscreen} title={locks ? 'fullscreen, and the browser stops keeping Escape, Tab and Ctrl-W for itself' : 'fullscreen — this browser will still keep some keys for itself'}>Fullscreen</Btn>
+          <a className="btn" href={cur.url} target="_blank" rel="noreferrer" title="the device directly, outside Ham Lab">Open ↗</a>
+          <Btn className="btn danger" onClick={() => remove(cur)}>Remove</Btn>
+        </>}
+        <Btn className="btn on" onClick={() => setAdding(true)}>+ Add</Btn>
+      </div>
+
+      {cur ? (
+        <div className={'kvm-frame' + (full ? ' full' : '')} ref={box}>
+          <iframe ref={frame} key={cur.id} src={`/kvm/${cur.id}/`} title={cur.name}
+            allow="fullscreen; clipboard-read; clipboard-write" />
+        </div>
+      ) : (
+        <div className="svc-empty muted">
+          {list.length === 0
+            ? 'No KVM yet. Add one with its address and its web page appears here.'
+            : 'Pick a KVM.'}
+        </div>
+      )}
+      {cur && !full && (
+        <div className="kvm-hint muted small">
+          Click the picture, then type — the keys go to the machine.
+          {locks ? ' Fullscreen also takes Escape, Tab and Ctrl-W back from the browser.' : ' This browser keeps Escape, Tab and Ctrl-W for itself; use the device’s own on-screen keys for those, or a Chromium browser.'}
+        </div>
+      )}
+      {adding && <AddDialog machines={machines} onClose={() => setAdding(false)} onAdded={(k) => { setAdding(false); setSel(k.id); load() }} />}
+    </div>
+  )
+}
+
+function AddDialog({ machines, onClose, onAdded }: { machines: MachineStatus[]; onClose: () => void; onAdded: (k: Device) => void }) {
+  const [url, setUrl] = useState('')
+  const [name, setName] = useState('')
+  const [machine, setMachine] = useState('')
+  const [err, setErr] = useState('')
+  const [busy, setBusy] = useState(false)
+  useEscape(onClose)
+  const save = async (e: FormEvent) => {
+    e.preventDefault(); setErr(''); setBusy(true)
+    try { onAdded(await api.addKVM(name.trim(), url.trim(), machine)) }
+    catch (e) { setErr(e instanceof Error ? e.message : 'failed'); setBusy(false) }
+  }
+  return (
+    <div className="modal-back" onClick={onClose}>
+      <form className="modal" onClick={(e) => e.stopPropagation()} onSubmit={save}>
+        <h3>Add a KVM</h3>
+        <label className="muted">Address — whatever you would type into a browser
+          <input autoFocus className="mono" value={url} onChange={(e) => setUrl(e.target.value)} placeholder="10.0.0.217" spellCheck={false} autoCapitalize="off" required />
+        </label>
+        <label className="muted">Name — optional; the address is used otherwise
+          <input value={name} onChange={(e) => setName(e.target.value)} placeholder="mac mini KVM" maxLength={64} />
+        </label>
+        <label className="muted">Attached to — optional, and only a label
+          <select value={machine} onChange={(e) => setMachine(e.target.value)}>
+            <option value="">—</option>
+            {machines.map((m) => <option key={m.name} value={m.name}>{m.host || m.name}</option>)}
+          </select>
+        </label>
+        <div className="muted small">
+          Ham Lab serves the device from its own address, so a KVM that only speaks plain HTTP
+          still works here, and it is behind this login rather than needing a second one. The
+          device itself is not changed and is never reachable from outside.
+        </div>
+        {err && <div className="error">{err}</div>}
+        <div className="svc-actions">
+          <button type="submit" className="btn on" disabled={busy || !url.trim()}>Add</button>
+          <span className="spacer" />
+          <button type="button" className="btn" onClick={onClose}>Cancel</button>
+        </div>
+      </form>
+    </div>
+  )
+}

web/src/Shell.tsx

@@ -12,6 +12,7 @@ import Jobs from './Jobs'
 import Updates from './Updates'
 import Disks from './Disks'
 import ZFS from './ZFS'
+import KVM from './KVM'
 import Files from './Files'
 import Top from './Top'
 import Machines from './Machines'
@@ -63,14 +64,15 @@ const GROUPS: Group[] = [
   { id: 'files', label: 'Files', icon: FolderIcon },
   { id: 'alerts', label: 'Alerts', icon: BellIcon },
   { id: 'machines', label: 'Machines', icon: '⌂' },
+  { id: 'kvm', label: 'KVM', icon: '⌨' },
   { id: 'users', label: 'Users', icon: '⚇' },
   { id: 'widgets', label: 'Widgets', icon: '▦' },
   { id: 'settings', label: 'Settings', icon: '⚙' },
 ]
 
-type View = 'terminal' | 'widgets' | 'docker' | 'alerts' | 'services' | 'jobs' | 'updates' | 'disks' | 'zfs' | 'usage' | 'files' | 'procs' | 'machines' | 'users' | 'settings'
+type View = 'terminal' | 'widgets' | 'docker' | 'alerts' | 'services' | 'jobs' | 'updates' | 'disks' | 'zfs' | 'usage' | 'files' | 'procs' | 'machines' | 'kvm' | 'users' | 'settings'
-const VIEWS: View[] = ['terminal', 'widgets', 'docker', 'alerts', 'services', 'jobs', 'updates', 'disks', 'zfs', 'usage', 'files', 'procs', 'machines', 'users', 'settings']
+const VIEWS: View[] = ['terminal', 'widgets', 'docker', 'alerts', 'services', 'jobs', 'updates', 'disks', 'zfs', 'usage', 'files', 'procs', 'machines', 'kvm', 'users', 'settings']
-const HUB_ONLY: View[] = ['machines', 'users', 'settings', 'alerts']
+const HUB_ONLY: View[] = ['machines', 'kvm', 'users', 'settings', 'alerts']
 
 // URL hash is the source of truth for where you are: #/<machine|hub>/<view>. Back and
 // forward work, reload restores the tab, and links can point at a page on a machine.
@@ -269,6 +271,7 @@ export default function Shell({ me: hubMe, onLoggedOut }: { me: Me; onLoggedOut:
         <main className="main" key={machine ?? 'hub'}>
           {view === 'settings' && <Settings me={hubMe} />}
           {view === 'users' && <Users me={hubMe} />}
+          {view === 'kvm' && <KVM machines={machines} />}
           {view === 'usage' && <Usage key={machine ?? ''} />}
           {view === 'machines' && <Machines hub={hubMe} onChanged={loadMachines} onOpen={(n) => { switchMachine(n); setView('procs') }} />}
           {view === 'widgets' && <Gallery />}
@@ -306,7 +309,7 @@ export default function Shell({ me: hubMe, onLoggedOut }: { me: Me; onLoggedOut:
         <span>{machine ? `${title} · ` : ''}{me.version.startsWith('v') ? me.version : 'v' + me.version}</span>
         <span>up {fmtUptime(me.uptime)}</span>
         <span className="spacer" />
-        <span className="muted">{view === 'widgets' ? 'Widgets' : view === 'docker' ? 'Docker' : view === 'alerts' ? 'Alerts' : view === 'services' ? 'Services' : view === 'jobs' ? 'Jobs' : view === 'updates' ? 'Updates' : view === 'disks' ? 'Disks' : view === 'zfs' ? 'ZFS' : view === 'usage' ? 'Usage' : view === 'files' ? 'Files' : view === 'procs' ? 'Processes' : view === 'machines' ? 'Machines' : view === 'users' ? 'Users' : view === 'settings' ? 'Settings' : activeTerm ? activeTerm.name : ''}</span>
+        <span className="muted">{view === 'widgets' ? 'Widgets' : view === 'docker' ? 'Docker' : view === 'alerts' ? 'Alerts' : view === 'services' ? 'Services' : view === 'jobs' ? 'Jobs' : view === 'updates' ? 'Updates' : view === 'disks' ? 'Disks' : view === 'zfs' ? 'ZFS' : view === 'usage' ? 'Usage' : view === 'files' ? 'Files' : view === 'procs' ? 'Processes' : view === 'machines' ? 'Machines' : view === 'kvm' ? 'KVM' : view === 'users' ? 'Users' : view === 'settings' ? 'Settings' : activeTerm ? activeTerm.name : ''}</span>
       </footer>
     </div>
   )

web/src/api.ts

@@ -133,6 +133,8 @@ export interface SpaceNode { name: string; dir: boolean; size: number; apparent:
 export interface SpaceTree extends SpaceNode { path: string; children?: SpaceTree[]; more_n?: number; more_size?: number; total: number }
 export interface SpaceFile { path: string; size: number; apparent: number; mtime: number }
 
+export interface KVM { id: string; name: string; url: string; machine?: string; added: string }
+
 export interface ZFSPolicy { id: string; name: string; dataset: string; recursive: boolean; every: 'hourly' | 'daily' | 'weekly' | 'monthly' | 'custom'; at: string; weekday: number; day: number; cron?: string; keep_for: string; keep_min: number; prefix?: string; enabled: boolean }
 export interface ZFSRun { at?: string; taken?: string; pruned?: string[]; error?: string }
 export interface ZFSExternal { tool: string; schedule: string; command: string; user: string; source: string; id: string; next?: number; last?: number }
@@ -184,6 +186,9 @@ export const api = {
   storage: () => req<{ devices: StorageDevice[]; zfs: ZFSInfo; smartctl: boolean }>('GET', '/api/storage'),
   smart: (dev: string, force = false) => req<SmartInfo>('GET', `/api/storage/smart/${dev}${force ? '?force=1' : ''}`),
   smartTest: (dev: string, kind: 'short' | 'long') => req<void>('POST', `/api/storage/smart/${dev}/test/${kind}`),
+  kvms: () => req<KVM[]>('GET', '/api/kvms', undefined, true),
+  addKVM: (name: string, url: string, machine: string) => req<KVM>('POST', '/api/kvms', { name, url, machine }, true),
+  removeKVM: (id: string) => req<void>('DELETE', `/api/kvms/${encodeURIComponent(id)}`, undefined, true),
   zfsOverview: () => req<ZFSOverview>('GET', '/api/zfs'),
   saveZfsSchedule: (p: Partial<ZFSPolicy>) => req<ZFSPolicy>('PUT', '/api/zfs/schedules', p),
   deleteZfsSchedule: (id: string) => req<void>('DELETE', `/api/zfs/schedules/${encodeURIComponent(id)}`),

web/src/styles.css

@@ -740,3 +740,13 @@ pre.diff .add { color: var(--ok); background: color-mix(in srgb, var(--ok) 12%,
 /* ZFS: the schedule dialog's controls match the rest of the modal forms */
 .modal select, .modal input[type=time], .modal input[type=number] { padding: 9px 10px; background: var(--bg); border: 1px solid var(--border); border-radius: 6px; color: var(--fg); font-size: 16px; }
 .modal .chips { margin-top: 2px; }
+
+/* ---- KVM: a device's own web page, framed ---- */
+.kvm { position: absolute; inset: 0; display: flex; flex-direction: column; background: var(--bg); min-height: 0; }
+.kvm-bar { display: flex; align-items: center; gap: 8px; padding: 8px 12px; border-bottom: 1px solid var(--border); background: var(--bg2); flex-wrap: wrap; }
+.kvm-bar .kvm-url { overflow: hidden; text-overflow: ellipsis; white-space: nowrap; max-width: 28ch; }
+.kvm-frame { flex: 1; min-height: 0; background: #000; position: relative; }
+.kvm-frame iframe { width: 100%; height: 100%; border: 0; display: block; background: #000; }
+.kvm-frame.full { background: #000; }
+.kvm-hint { padding: 6px 12px; border-top: 1px solid var(--border); }
+@media (max-width: 800px) { .kvm-bar .kvm-url { display: none; } }