Skip to main content

Service lifecycle & off switch

Service registration​

Every install path ends in the same command:

lumen-agent service install --start

One implementation writes the systemd unit, the launchd plist, or the SCM registration. Two field lessons are baked in:

  • Reinstalls replace the loaded service. On macOS, bootstrapping over an already-loaded label fails and leaves the stale daemon running an old config — so activation boots the label out first and retries.
  • "Registered" is not "serving." After --start, the command polls /v1/health (and the proxy's /lumen/health when enabled) and fails loudly with the log location if either never answers.

Verify any machine in one command:

lumen-agent status        # exit 0 answered, 3 daemon down, 1 no report

The off switch​

sudo lumen-agent disable --reason "incident 2026-08-01"
sudo lumen-agent enable

disable writes a root-owned marker (/etc/lumen/disabled), and every collector reads it before it acts — including the Claude Code hook guard, which never talks to the daemon and survives service stops and uninstalls. It is the only thing that turns that guard off.

What disable does not do is take anything down:

  • Every listener stays open; the proxy forwards byte-for-byte, streamed responses included.
  • Nothing is un-routed — the machine's tooling still points at the proxy, and a disabled proxy still answers its health probe (with "disabled": true) so the fail-open machinery keeps holding.
  • The daemon keeps heartbeating, so the endpoint reads as disabled, not offline.

Nothing is recorded while it is off — a quiet findings file during that window means the agent was not looking. lumen-agent status prints the control block first, so it is never a guess.

Uninstall​

sh install.sh --uninstall        # or: lumen-agent service uninstall

Uninstalling un-routes the machine as well as removing the binary — an agent removed while a settings file still pins its proxy would leave the machine pointed at a dead port:

  • The revert runs as root, but every target lives in a home directory, so the human is resolved from SUDO_USER and rewritten files are chowned back to them.
  • Other users are named, never rewritten — each is told the lumen-agent autoconfig revert to run.
  • A failed revert never fails the uninstall. Removing a security agent must not be the operation that gets stuck.

Config and state are kept (/etc/lumen, /var/lib/lumen): findings are evidence, and deleting them is a separate, deliberate act.

Upgrades​

lumen-agent upgrade --check
lumen-agent upgrade --to v0.5.0
lumen-agent upgrade --rollback

The manual path reads version.json from the download CDN and verifies the archive checksum before the atomic swap. Fleet-driven staged rollouts arrive with the control plane.