Skip to main content
Beacon runs a local collector on your machine, points your agent runtimes at it, and writes normalized events to a JSONL log you own. On macOS the collector runs as a launchd job. There are two ways in, and which one you want depends on whether you are setting up your own machine or a fleet.

​
Your own machine

Install the CLI, then the endpoint
beacon endpoint install with no flags is a user-mode install: everything lives under ~/.beacon/endpoint, the launchd job is a LaunchAgent in your own domain, and nothing needs root. That is the right choice for a single developer. Then confirm it:
Verify
On a fresh install doctor reports one warning — harness_observed, saying telemetry is configured but no matching event has been seen yet. That is not a problem; it clears the first time you run your agent. What matters is 0 failure(s).

​
A managed fleet

For deployment across machines, use the signed, notarized, and stapled .pkg attached to each release. Installing it performs a system-mode install: configuration under /Library/Application Support/Beacon/Endpoint, a LaunchDaemon, and the runtime log at /var/log/beacon-agent/runtime.jsonl. The package also configures the console user’s agent runtime, because a system endpoint runs as root and the collector is useless if nothing is exporting to it.

Jamf Pro

Package deployment, policy scripts, validation, and Extension Attributes.

Fleet

Package and user-context deployment helpers.

Rippling

Package deployment through Rippling MDM.

All MDM options

Compare the supported management paths.

​
Managing the service

The collector is an ordinary launchd job:
User mode
System mode
KeepAlive restarts the collector if it exits and RunAtLoad starts it at login or boot. Both are set by the install; you do not configure them. If the job or its plist is missing or broken, repair it without reinstalling:
Repair

​
What is macOS-specific

Most of Beacon behaves identically everywhere — the event schema, the collector, hooks, the dashboard, threat detection. These are the parts that do not: Two of those have no Linux equivalent and are worth knowing if you run a mixed fleet: notarization gives macOS an OS-level authenticity check that Linux has no counterpart for, and the MDM assets are macOS-only. See Linux for how that platform differs.

​
Updates

Upgrade the CLI with Homebrew, or let Beacon update a package install in place:
Update in place
--apply downloads the release package, verifies its SHA-256 and its Apple notarization, installs it, restarts the collector, and rolls back if the new version fails its health check. The command reports which verification it performed, so a mixed fleet can tell the two platforms apart: macOS gets sha256+notarization, Linux gets sha256 because there is no OS-level equivalent. --apply requires a package install. A Homebrew install is upgraded with brew upgrade beacon.

​
Uninstall

Remove the endpoint
--keep-logs and --keep-config are available if you want to keep either.

Endpoint install

All install flags, harness selection, and hook installation.

Endpoint paths and ports

Where Beacon writes config, logs, and service definitions on each platform.

Endpoint status

Inspect collector health, runtime log state, harnesses, and diagnostics.

Local dashboard

Browse captured sessions, timelines, and event detail locally.