Host Agents

Host Agent (repo: hostzu/) is a lightweight inventory agent for servers and workstations. It is implemented (both phases below) as of 2026-07-19.

Status

Layer	State
Spec (`hostzu/spec.md`)	Implemented
Phase 1 — Cloud-direct (Backend, `hostzu-agent`, Frontend UI)	Shipped
Phase 2 — Edge gateway dual-path (`edgezu-hostagent-gateway`, transport switching)	Shipped, with known gaps — see below
These docs	Reflect the actual implementation

Known Phase 2 gaps (tracked in root `TODO.md`)

Edge does not yet advertise _edgezu-gateway._tcp over mDNS — hostzu-agent’s discovery client exists, but nothing on Edge answers it yet, so hosts always fall back to Cloud-direct today.
Elevated data collection (BitLocker/LUKS, local users, patches, services) is a payload skeleton only — always collected: false.
Agent auto-update distribution (spec section 10) is not implemented.

Boundaries

In scope (MVP)	Out of scope
Periodic + change-triggered inventory snapshots	Agentless SSH/WinRM scanning
Prefer Edge gateway; Cloud fallback	Remote command execution on host
MAC-based Asset merge in CMDB	Continuous process/network telemetry (phase 2+)

Note: change-triggered snapshots (IP/software/hostname/restart diff detection) are not yet implemented — the agent currently only sends a full snapshot on a fixed interval (snapshot_interval_hours, default 12h).

Architecture

flowchart LR
  Host[Host Agent] -->|prefer, if Edge advertises| EdgeGW[Edge hostagent gateway]
  Host -->|fallback: Bearer host_token| Ingest[Ingestor /v1/ingest]
  EdgeGW -->|X-Device-Key, queued via edgezu-agent| Ingest
  Ingest --> Asset[CMDB Asset]

host_inventory flows through the same Ingestor service as Edge’s own telemetry/log/discovery data (see Ingestor overview) — Cloud Backend has no ingest endpoint of any kind. Ingestor’s internal/domain/hostinventory package handles the kind’s extra needs (blob storage for the raw JSON, MAC-based Asset-merge) that the generic per-kind pipeline doesn’t. Edge-proxied snapshots go through the normal push_ingest/ingest_queue path (device-key auth, host_id in the payload), so they get the same offline-durability as every other kind; a host with no reachable Edge gateway posts directly to Ingestor with its own Bearer host_token.

Build specification (PL): hostzu/spec.md at monorepo root.

vs Edge claim-code

	Edge appliance (shipped)	Host Agent (shipped)
Bootstrap	`monozu edge register` + internal assign	`enrollment_secret` per site + Cloud UI approve
Actor	Technician at device	Silent rollout (GPO/Intune)
Runtime credential	`api_key`	`host_token` (TTL + refresh, not indefinite)