Agent ops (healthz, uninstall, proxy, pinning)

What it is

The cluster of operational knobs the customer’s ops team will reach for once the agent is in their fleet. Together they cover the day-2 needs: confirm it’s alive, take it down cleanly, run it behind a corporate proxy, control its update cadence.

What it produces

• 127.0.0.1:7780/healthz: loopback-bound JSON endpoint with the agent’s id, version, control_plane URL, current scope, scan concurrency. Curlable from the host without going through Umbra.
• --uninstall: revokes the credential server-side (cascade- cancels any queued tasks), wipes state.json, exits.
• --proxy / HTTPS_PROXY / NO_PROXY: outbound HTTPS proxy for control-plane traffic. Probe traffic (to your internal services) is NEVER proxied. Those have to hit the real target.
• --pinned-version: refuses any auto-update offer whose version doesn’t match.
• JSON config file: --config <path> or auto-search /etc/umbra-agent/config.json then $STATE_DIR/config.json. Same keys as the flags.

What to use it for

• A customer ops team running their own monitoring on the agent host (curl /healthz from a Prometheus exporter)
• Decommissioning a host cleanly (—uninstall before reimaging)
• Operating inside a corporate network that forces outbound traffic through a proxy
• Pinning a specific agent version during a vendor QA window

Why it matters

A SaaS that ships an agent without these knobs has shipped a “black box that occasionally needs an SSH visit.” With them, the agent is a self-contained operable unit the customer’s SRE team can run exactly like any other systemd / docker service.

Why it’s valuable

• Loopback-only healthz. Never leaves the host; no inadvertent scope expansion.
• Clean uninstall. Revoke + state-wipe in one command: no orphaned dashboard rows, no half-deleted credentials.
• Probe traffic NEVER proxied. A corporate proxy can serve the control plane all day; probes still go direct to the target inside the network.
• Config file precedence is explicit. env > flag > file > default. A kubectl exec debugging session that sets --scan- concurrency 32 won’t get overridden by what’s in the YAML.

How to use it

The most common shapes:

# systemd / docker happy path
umbra-agent --config /etc/umbra-agent/config.json

# behind a corporate proxy
HTTPS_PROXY=http://corp-proxy:3128 umbra-agent

# pin to a specific version during QA
umbra-agent --pinned-version 0.4.0

# decommission cleanly
umbra-agent --uninstall

# debug: quick scan-concurrency drop without restart of unit file
SYSTEMD_UNIT_ENV='--scan-concurrency 32' systemctl restart umbra-agent

Config file shape (all fields optional):

{
  "control_plane": "https://app.umbrascope.com",
  "state_dir": "/var/lib/umbra-agent",
  "scan_concurrency": 64,
  "healthz_addr": "127.0.0.1:7780",
  "proxy_url": "http://corp-proxy:3128",
  "pinned_version": "0.4.0"
}