Foreman
Live Herdr agent monitoring dashboard hardware

Foreman is a lightweight Raspberry Pi touchscreen interface that monitors live Herdr agents and focuses their panes with a tap.

The kiosk UI uses TypeScript and Preact, bundled into the Go binary with esbuild.

Append ?preview=working, ?preview=blocked, ?preview=done, or ?preview=idle to the dashboard URL to render a synthetic agent in that state without an agent connection. Use ?preview=all to render every state together. Preview mode is client-side only and does not change Foreman or Herdr state.

Screenshots / Photos

Install

• mise run install-host installs the Go service and native macOS menu-bar controller.
• FOREMAN_SSH_TARGET=pi@raspberrypi.local mise run install-kiosk installs the Chromium autostart entry, desktop launcher, and Raspberry Pi resource reporter. The target defaults to the foreman SSH alias.
• mise run vnc-open opens the Pi display through its local-only VNC server and an SSH tunnel.

The menu-bar app and kiosk settings page share the resource polling interval. Five seconds is the default; 10, 30, and 60-second intervals are also available. Compact mode fits up to 15 agent tiles at 800×480.

Clicking an agent focuses its Herdr pane and activates the terminal selected under Focus Terminal in the Foreman menu-bar menu. Ghostty is the default; detected iTerm2 and WezTerm installations are also available, and running terminals display their app icon. Select Disabled to focus the pane without activating an app.

Installing a kiosk update closes an existing Foreman Chromium kiosk after replacing the files. Open the Foreman desktop launcher to start the updated version.

Discovery and pairing

Foreman Macs advertise _foreman._tcp.local with Bonjour. The kiosk opens its local discovery page, lists every compatible Mac on the LAN, and uses each Mac's stable installation ID so DHCP address changes do not break the relationship.

To pair a kiosk:

1. Choose Allow New Kiosk from the Foreman menu on the Mac. Pairing remains open for three minutes.
2. Select that Mac on the kiosk and choose Start pairing.
3. Verify that both devices show the same six-digit code, then approve it on each device.

Each Mac can authorize multiple kiosks. A kiosk keeps a separate credential for every Mac, so Settings → Switch Mac reconnects to a previously paired computer without another code. The Mac menu can revoke one kiosk or all paired kiosks.

Pairing uses ephemeral P-256 ECDH and displays a short authentication string to detect a person-in-the-middle. The resulting 256-bit device secret and the Mac's TLS certificate fingerprint are encrypted during pairing. Dashboard and satellite traffic then use certificate-pinned TLS 1.3, while WebSocket upgrades additionally require a fresh HMAC signature, timestamp, and one-time nonce.

See docs/SECURITY.md for the threat model, trust bootstrap, storage guarantees, and recovery behavior.

Package build approval

esbuild@0.28.1 is allowed to run its postinstall because it selects and verifies the platform binary. The reviewed release is OIDC trusted-published with SLSA provenance and a registry signature; its npm gitHead matches upstream tag v0.28.1, the tarball matches registry integrity, and aube audit reports no advisories.

Hardware

• Raspberry Pi 4 - 2GB RAM¹ (but any raspberry pi supported by the touch screen will do - it's just what I had on hand. The RPI4 is sitting at 32% RAM when idle (0.6GB used))
• Hosyond 7inch Touchscreen IPS Display¹ (other touchscreens should work too - but this is the one I tried and it's relatively affordable and comes with all the hardware you need)
• MacOS (for the host)

Trademark notice

All agent names, logos, and trademarks, including the Herdr name and logo, are the property of their respective owners. Foreman is an independent project and is not affiliated with, sponsored by, or endorsed by those owners.

Footnotes

1. The Amazon links above are affiliate links. I may earn a small commission from qualifying purchases at no additional cost to you. ↩ ↩²