diskless-workstation/files/hostapi/README.md

fleet-hostapi — workstation host-info agent

A tiny read-only, loopback-only Go HTTP service that runs on the diskless workstation and reports facts about the machine the kiosk renders on. It is the OS-side implementation of the contract in ../../HOST-API.md (authored alongside the kiosk-app SPA that consumes it).

GET http://localhost:9099/v1/host  ->  application/json   (os, hardware, net, kiosk, agent)
GET http://localhost:9099/healthz  ->  200 ok

Properties (and why)

• Loopback only. Binds 127.0.0.1; refuses to start on any routable address. Host facts must never reach the boot LAN.
• Read only. No endpoint mutates anything; it reads /proc, /sys, /etc/os-release, and the build-time facts file.
• No per-host state baked in (invariant #1). Host-specific fields (kernel, hostname, IP, MAC, board, uptime) are read at runtime. The only baked facts are image-generic — image version + weston/chromium versions — written to /etc/fleet-hostinfo.json by the build provisioner.
• Stdlib only → reproducible build (the verity hash is a security property). Built CGO_ENABLED=0 -trimpath -buildvcs=false -ldflags=-buildid=; identical bytes across builds with the same Go toolchain.
• CORS + Private Network Access. The SPA is cross-origin and the fetch is a Chromium private-network request, so responses carry Access-Control-Allow-Private-Network: true. The matching browser-side allowance is in files/kiosk/chromium-kiosk-policy.json (InsecurePrivateNetworkRequestsAllowedForUrls, scoped to the kiosk origin).

Build / install

Done by the 2b-hostapi provisioner in diskless.pkr.hcl: installs the Go toolchain, builds the static binary to /usr/local/bin/fleet-hostapi, writes the facts file, installs + enables fleet-hostapi.service, and adds the binary to fapolicyd trust (2c-STIG-postfix). The toolchain is removed in 2d hygiene — only the static binary ships.

Local build:

CGO_ENABLED=0 GOOS=linux GOARCH=amd64 go build -trimpath -buildvcs=false \
  -ldflags '-s -w -buildid=' -o fleet-hostapi .

Config (env, set in the unit)

Var	Default	Notes
FLEET_HOSTAPI_ADDR	127.0.0.1:9099	must be loopback
FLEET_HOSTAPI_ALLOW_ORIGIN	*	tighten to the kiosk origin in prod
FLEET_HOSTAPI_FACTS	/etc/fleet-hostinfo.json	build-time facts