hamlab/README.md

Ham Lab

Web-based Linux management console for bare-metal Debian, in the style of the Proxmox web UI. Named after Ham the cat (see also HamTV).

Status: v0.1 — persistent web terminals and a live Dashboard tab. Scope and roadmap in PLAN.md.

Runs on any Linux box

One static Go binary with the UI embedded; no cgo, no Node at runtime, no agents. The Dashboard reads /proc and /sys directly (CPU, memory, hwmon or thermal-zone temps, fans, NICs, block devices, mounts) so it works the same on x86 and ARM, bare metal or VM, and just leaves a section empty when the hardware has nothing to report. UPS status is optional and picked up from whichever of pwrstat, NUT (upsc) or apcupsd is installed.

make build                      # web + Go, or: make build-arm64 for a cross-compile
./deploy/install.sh             # installs the binary + a systemd unit for the invoking user
hamlab passwd                   # set the login password (config in ~/apps/hamlab/)
sudo systemctl start hamlab     # listens on 127.0.0.1:8100 by default; set "listen" in config.json

Terminals run as the user the service runs as, with that user's login shell.

Managing several machines

Install Ham Lab on each host. On the ones the hub should reach, add "tls": "auto" and a LAN listen address to config.json (a self-signed certificate is generated on first start). Then on the hub, open Machines, enter a name, the address (https://host:8100) and that machine's Ham Lab password once. The hub pins the certificate, keeps an access token, and every tab works against the chosen machine through the switcher at the top of the rail.

Updating: make deploy on the hub installs the new build there and then pushes it to every managed machine (hamlab push-nodes), which install it and restart. The Machines page flags machines running an older version and offers the same push per machine. Mixed architectures are fine: make deploy also cross-compiles arm64, and the hub sends each machine the build for its own architecture.

• On core it is public at https://hamlab.bigham.dev behind Nginx Proxy Manager.
• Installable as a PWA.