cjpitzi Surface — drive the office wall display
Chris has a permanent, interactive office display (KVM-attached, on pve2
HDMI-2) driven by the surface command (on PATH; private repo at
~/repos/office-presence). surface <X> means: put the right live view of X
on that display. You pick the source and build the URL. This is additive —
still answer in chat / trigger other skills.
Plain text/code ("surface foo.py") stays in chat unless the user says "on the display".
The display is a persistent, full browser (tabs + address bar), not a locked
kiosk. surface page/url/show each open a new focused tab — they never
replace what's up or restart the browser, so Chris's own tabs and earlier
surfaced views stay open and he can flip between them. surface home refocuses
the household dashboard tab; surface stop closes just the tabs surface page
opened. Tabs accumulate over a session — that's expected; close them from the
browser UI or leave them.
Preconditions
- LAN-only.
surfaceSSHes directly to pve2. A network-isolated cloud/cowork session cannot reach it — say so rather than pretending. Confirm reachability withsurface stateif unsure. - Authed services (Grafana ✓ already logged in, Axiom, private HA) need the display logged in once at the KVM. Public GitHub / public-dashboard URLs just work.
Workflow: identify → show → file
1. Identify the source + scope
Pick what fits X; compose multiple into panes if it spans sources.
| Source | Use for | How to build the URL |
|---|---|---|
Grafana Cloud (pitzilabs.grafana.net, display logged in) |
metrics & Loki logs: throughput, host/NAS stats, the Claude runner fleet | grafana MCP search_dashboards → find dashboard/panel → …/d/<uid>/<slug>?viewPanel=<id>&from=now-30d&to=now&refresh=10s |
| Axiom | Firewalla logs (ACL/blocks, Zeek) — event/log-shaped X | Axiom dataset/query URL (one-time KVM login) |
| GitHub (public PitziLabs repos render with no login) | repos, PRs, Actions runs | github.com/<org>/<repo>/actions/runs/<id> — find via github MCP / gh |
| Home Assistant | home/device state | a Lovelace view URL |
| Firewalla MCP | when X isn't in Grafana/Axiom (get_alarms, search_flows, get_wan_usage, get_network_stats, get_top_talkers) |
use the data to decide which dashboard/view to surface |
homelab-observability maps what's measured where. Prefer a real, navigable
link over a constructed static page; build a page only for something with no URL
(a diagram) or to compose several sources into panes.
2. Show it
surface url NAME # a saved favorite (fastest — check `surface list` first) → new tab
surface show URL [opts] # any http(s) URL → new focused tab
surface page NAME # a built library page (offline Mermaid) → new tab
surface push-site DIR # publish a static site dir to pve2 (durable, http://web.lan/)
surface home # focus the household dashboard (home) tab
Options: --open (xdg-open the snapshot), --no-snap, --settle SECS, --port N.
For anchor deep-links into a long page, add --settle 4 so the scroll lands before
the snapshot.
3. Verify (always) — vision check
surface verify # lists the open tabs + grabs a frame of the frontmost
Then Read the PNG it wrote (./surface-<UTC>.png) and confirm the frontmost
tab shows the expected content — not a login wall, blank, or error. The tab
landing frontmost is the one surface just opened, so the frame is your check
that it rendered. Use surface snap for an extra frame.
4. File it for fast recall
For anything worth seeing again:
surface save-url NAME URL "Title" # writes urls.json
Then commit office-presence so it persists, and tell Chris the short name:
cd ~/repos/office-presence && git add urls.json && git commit -m "Add '<name>' URL favorite — <what>"
For multi-source composites, add a page under pages/ + a library.json entry
instead. End commit messages with the Co-Authored-By trailer.
State & recovery
surface state # open tabs + page-server state (and a reachability check)
surface list # library pages + URL favorites
surface stop # stop the page server, close its tabs, focus home
The persistent browser launches on the household dashboard across pve2 reboots;
systemd Restart=always recovers crashes, and dashboard-refresh.timer reloads
just the dashboard tab every 6h to clear its heap leak. The pve2 plumbing
(display-tab for tab control, display-show to (re)launch, snapshot-server on
:9999, dashboard-display.service) is deployed from this repo's host/ by the
gitops loop — if surface fails on the SSH/display-tab step, check that plumbing.
If display-tab reports "no DevTools endpoint", the screen is in fullscreen kiosk
mode (no debug port) — surface home relaunches the interactive browser.
Example
"surface the last 30 days of host throughput" → grafana MCP search_dashboards
for the throughput panel → surface show '…/d/<uid>/…?viewPanel=<id>&from=now-30d&to=now&refresh=10s'
→ surface verify + Read the PNG → surface save-url host-throughput-30d <url> "Host throughput 30d"
→ commit. Next time: surface url host-throughput-30d.