Skip to main content

​
Check for updates

Running bare beacon in an interactive terminal shows a cached update notice when a newer release is available. It does not wait on a network request: when the cache is more than a day old, Beacon refreshes it in the background for the next run. Use beacon version check before upgrading to confirm whether a newer release is available:
Check for updates
When an update is available, Beacon prints the latest version, the installed version, Homebrew upgrade guidance, and a release download URL. The automatic notice is skipped for scripts, pipes, redirects, other commands, CI, and development builds. Set BEACON_UPDATE_CHECK=0 to disable it without disabling the explicit beacon version check command.

​
Upgrade with Homebrew

Upgrade Beacon with the standard Homebrew flow:
Upgrade Beacon

​
Self-updating endpoint packages

For Apple Silicon systems installed from the signed endpoint package, Beacon can check the GitHub Release manifest and optionally apply newer signed packages. Self-update is off by default and is available only for the system package install under /opt/beacon. Homebrew and archive installs should continue to use their normal upgrade flow. Behind the scenes, beacon endpoint update reads update-manifest.json, selects the package artifact for the local architecture, downloads it into the endpoint update staging directory, verifies the manifest checksum, Developer ID Installer signature, and Gatekeeper install assessment, then runs Apple’s installer. The package’s installer signature must come from Asymptote Labs’ Apple team (3A98D35XJR), which is built into beacon rather than read from the unsigned manifest, and both the manifest and the package must be fetched over https (plain http only to a loopback mirror, and never through a redirect). The package postinstall restarts the local collector, restores configured Vector forwarders, re-renders a connected endpoint’s Beacon Cloud forwarder config from the new version’s pack (see Keeping the forwarder config current), reconciles the updater LaunchDaemon, and the updater health-checks the new install. If the new install is unhealthy, Beacon restores the previous /opt/beacon tree. Update activity is written to the local system log beside the runtime log:

​
Modes

Beacon supports three endpoint update modes: Scheduled checks run from the root launchd job com.beacon.endpoint.updater. The default package schedule uses local business hours with jitter, so devices do not all fetch and install at exactly the same time.

​
Check-only monitoring

Enable check-only endpoint update monitoring
Disable the background check job with:
Disable endpoint update monitoring

​
Auto apply mode

Enable full automatic package updates with:
Enable automatic endpoint package updates
The status output should show:
Disable automatic updates and remove the updater LaunchDaemon with:
Disable automatic endpoint package updates

​
Manual apply

When a newer signed endpoint package is available, apply it manually with:
Manually apply an endpoint package update

​
Troubleshooting self-update

Check installed version and updater state:
Inspect updater state
Check the updater LaunchDaemon:
Inspect updater launchd job
Run the scheduled updater path immediately for testing:
Run scheduled updater immediately
Common states: Successful updates clean staging state under:
Only .update.lock should remain after a healthy update. If a future update fails and rollback succeeds, Beacon keeps a small last_failure.json diagnostic instead of retaining a full old install tree.

​
Repair endpoint configuration

If you run Beacon as a local endpoint service, reapply managed service files and telemetry configuration after upgrading:
Repair endpoint configuration after upgrade
beacon endpoint repair preserves runtime logs while reapplying service files, collector configuration, harness telemetry settings, and forwarding destinations. On an endpoint connected to Beacon Cloud it keeps the forwarder, its device key and its Vector checkpoints, and re-renders vector.toml from the upgraded version’s pack with the recorded privacy mode, so a Homebrew or archive upgrade picks up forwarder fixes without a re-connect. See Keeping the forwarder config current.
On v0.0.43 or newer, use beacon endpoint doctor --fix when you only need supported health-check drift remediated without a full repair.

Install Beacon

Install the Beacon CLI with Homebrew or platform archives.

beacon version

Display the installed version and check for released updates.

Endpoint repair

Reapply service files and telemetry configuration.

Endpoint health checks

Validate endpoint health and apply supported fixes.