Skip to main content

Endpoint agent

lumen-agent is the host sensor: a single static Go binary that runs as an OS service (systemd, launchd, SCM) and needs zero inbound ports. It is the hardest and most valuable piece of the product — the collector that makes a machine observable the moment the agent is installed.

What runs on the device​

lumen-agent (Go daemon / service)
 ├─ Local inspection API   loopback HTTP, 127.0.0.1:7645 — for SDKs, hooks, apps
 ├─ LLM proxy              127.0.0.1:7646 — captures provider traffic itself
 ├─ MCP proxy              stdio wrapper for agentic tool traffic
 ├─ Claude Code hook guard fresh process per event, enforces without the daemon
 ├─ Context enricher       process, user, device posture
 ├─ Local detection engine regex, Aho-Corasick, entropy, classifier, bloom filter
 ├─ Policy cache           hot-reloaded, ~2 s after a file change
 ├─ Spooler                on-disk queue, survives restarts and offline windows
 └─ Transport              outbound-only mTLS to the Lumen cloud

The parts worth knowing​

  • The inspection API answers "is this dangerous?" for anything on the machine that asks — see Local API.
  • The proxy is what makes the agent capture rather than wait to be called: AI tooling is pointed at 127.0.0.1:7646 by autoconfig, and prompts are inspected before they leave the machine.
  • The hook guard covers what the proxy cannot see — the shell commands, file writes and fetched pages of an agentic session — and keeps enforcing even if the daemon is stopped or uninstalled.
  • The spooler buffers findings on disk with backpressure, so capture never blocks the user's AI tool and nothing is lost offline.
  • Policy hot-reload: save the file, and the running agent picks the change up within about two seconds. An invalid edit is rejected and the previous version stays live.

Enrollment and transport​

The agent enrolls with a tenant-scoped enrollment token (install.sh --token=… or MDM-pushed). It generates a keypair, submits a CSR, and receives an mTLS client certificate — the tenant binding is fixed at enrollment and never self-asserted. Telemetry flows up the outbound-only mTLS channel; policy updates flow down on the same channel.

note

The agent is fully functional locally today — inspection, capture, policy, findings. The cloud transport (enrollment, mTLS uplink) arrives with the Lumen control plane.

Platforms​

{linux, darwin, windows} × {amd64, arm64}, built with CGO_ENABLED=0 — one dependency-free file per platform. See Install the agent.