The principle behind the kiosk agent is that every action a visitor can take in the HydraExperienceNet Qt kiosk UI should also be triggerable by a remote operator via a named CLI subcommand — so that hydracluster exec can fully manage the kiosk without physical presence.
Current CLI subcommands: run, install, uninstall, update, check-update, version, stream-start, stream-stop.
The Go agent exposes a local API at 127.0.0.1:9740 that the Qt kiosk app calls for all its actions. The kiosk also posts to 127.0.0.1:9741 (the Qt app's own API) for window show/hide — those calls are made internally by the Go agent and do not need separate CLI commands.
| Endpoint | Method | Purpose | CLI subcommand | Gap? |
|---|---|---|---|---|
GET /api/v1/config |
GET | Returns district + venue config for the kiosk | None | YES |
GET /api/v1/experiences |
GET | Returns the venue experience catalog | None | YES |
POST /api/v1/stream/start |
POST | Start a stream to a named experience | stream-start <experience> |
No |
POST /api/v1/stream/stop |
POST | Stop the active stream | stream-stop |
No |
GET /api/v1/stream/status |
GET | Poll current stream status (idle/finding_body/pairing/streaming/error) | None | YES |
GET /api/v1/screenshot |
GET | Get a live screenshot of the kiosk display | None | YES |
GET /api/v1/logs |
GET | Get the last 200 lines of the agent log | None | YES |
POST /api/v1/warnings/autologin/suppress |
POST | Suppress the autologin-disabled warning permanently | None | YES |
POST /api/v1/warnings/notifications/suppress |
POST | Suppress the notifications-not-silenced warning permanently | None | YES |
5 read endpoints and 2 warning-suppression endpoints have no CLI equivalent.
stream-statusPurpose: Print the current stream status from GET /api/v1/stream/status. Useful in operator scripts and automated health checks.
hydrahead stream-status
# output: {"status":"streaming","host":"10.10.10.5","app":"mercator-talks","error":""}
show-configPurpose: Print the district + venue config the agent loaded from GET /api/v1/config. Lets operators verify the kiosk is registered to the correct venue without SSH.
hydrahead show-config
# output: {"district":"bxl1","venue":"cloud-seven"}
list-experiencesPurpose: Print the experience catalog for this kiosk's venue from GET /api/v1/experiences. Operators can verify catalog sync without opening the kiosk UI.
hydrahead list-experiences
# output: JSON array of experience objects
get-screenshotPurpose: Save or stream the live kiosk screenshot from GET /api/v1/screenshot. Operators can inspect the display state without TCC-gated screenshot loops.
hydrahead get-screenshot --output /tmp/kiosk.jpg
get-logsPurpose: Fetch the last N lines of the agent log from GET /api/v1/logs. Quick remote triage without needing SSH or file access.
hydrahead get-logs [--lines 200]
# prints log lines to stdout
suppress-warning autologinPurpose: Suppress the autologin-disabled startup warning by calling POST /api/v1/warnings/autologin/suppress. Alternative: a single suppress-warning command with a positional arg (autologin or notifications).
hydrahead suppress-warning autologin
hydrahead suppress-warning notifications
internal/cli/stream.go: call the local API at 127.0.0.1:9740 and print the JSON response to stdout.get-screenshot is the only command that needs binary output handling (write JPEG bytes to a file).suppress-warning command could be a single command with a positional argument (autologin or notifications) to keep the command surface compact.pkg/client/localapi.go.