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, plus 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 at /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 (or, when that is root, from the login session) and their files are reverted by the agent running as them, so they stay theirs.
  • Root's own home is reverted too when an older agent routed it (installs made from a sudo -i shell by agents v2.1 to v2.5 did).
  • Other users are named, never rewritten. Each is told the lumen-agent autoconfig revert to run. When the uninstall does not run as root and root's home is still routed, it names sudo lumen-agent autoconfig revert --user root for it.
  • A failed revert never fails the uninstall. Removing a security agent must not be the operation that gets stuck.
  • The person's hourly inventory scan goes too. install.sh --uninstall removes the per-user schedule the install set up (the lumen-inventory systemd --user timer on Linux, the LaunchAgent on macOS) as that person, before the binary goes, so there is no separate lumen-agent inventory uninstall to run first. Root's own schedule is never touched. Like the revert, this step never fails the uninstall: if it cannot act as the person, the service, the browser policy and the binary are still removed.

Config and state are kept in /etc/lumen and /var/lib/lumen: findings are evidence, and deleting them is a separate, deliberate act. The one file the uninstall does remove there is coverage.json, the routing coverage reports: they describe the routing the uninstall just undid, and a reinstall would otherwise start by claiming it.

Upgrades​

lumen-agent upgrade --check
lumen-agent upgrade --to v1.0.0
lumen-agent upgrade --rollback

The manual path reads version.json from the download CDN and verifies the archive checksum before the atomic swap. --to names an exact version and counts as operator intent, so it can move the agent backwards as well as forwards.

Upgrades driven from the console ship as well. An admin can pin one endpoint, or every endpoint behind the current release, and an endpoint with auto-upgrade turned on takes each new release on its next check-in. Auto-upgrade accepts only a newer release build, so it never moves an agent backwards on its own. What does not exist is a staged rollout. There is no way to send a release to part of the fleet first and the rest later. See Endpoints.

Linux endpoints installed by agent v2.1 to v2.5

Those installers wrote the per-user inventory job's systemd --user units without enabling them, so the job never ran, and an upgrade does not re-run that step. That job is what keeps the console's coverage figure current, so after upgrading run this once, as root, for each person who uses the machine:

sudo lumen-agent inventory install --user <login name>

It enables the job, and starts it at once if that person is logged in. macOS endpoints and fresh installs need nothing.