Skip to content

The cross-harness, self-improving memory layer for AI agents. Join our community: https://discord.com/invite/zdNChS2fBu

9.6 KB
Raw Blame
---
title: "macOS"
description: "Install the Beacon endpoint on macOS with Homebrew or the signed package, and understand how the launchd service is managed"
---

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

```bash title="Install the CLI, then the endpoint"
brew update
brew trust asymptote-labs/tap
brew tap asymptote-labs/tap
brew install beacon
beacon endpoint install
```

`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:

```bash title="Verify"
beacon endpoint status
beacon endpoint doctor
```

On a fresh install `doctor` reports one warning, `harness_observed`, which says 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.

A first install from the package sets up [restricted log access](/security/restricted-log-access): only the collector writes the log, and only root and the `beacon-log` group can read it. An upgrade keeps the mode the endpoint already has. A person who installs the package in Installer.app is added to `beacon-log`, so the dashboard, `beacon traces` and `beacon share` work for them after they log in again; an MDM install adds nobody and turns the [local dashboard](/cli/dashboard#turning-the-dashboard-off) off, unless `BEACON_DASHBOARD=enabled` is set. See [Package installs](/security/restricted-log-access#package-installs).

### Settings for MDM installs

An MDM installs the package without letting you set the environment of its install script. Push the settings as a configuration profile for the preference domain `com.beacon.endpoint` instead, with keys named exactly like the variables, and the install script reads them from the managed preferences:

```xml title="Configuration profile payload (com.beacon.endpoint)"
<dict>
  <key>PayloadType</key>
  <string>com.beacon.endpoint</string>
  <key>BEACON_LOG_ACCESS</key>
  <string>restricted</string>
  <key>BEACON_LOG_READERS</key>
  <string></string>
  <key>BEACON_ENDPOINT_HARNESSES</key>
  <string>claude,codex,cursor</string>
</dict>
```

An empty `BEACON_LOG_READERS` means nobody is added to `beacon-log` implicitly. Without an MDM, write the same keys to the local preferences as an administrator, before installing:

```bash title="Local install settings"
sudo defaults write /Library/Preferences/com.beacon.endpoint BEACON_LOG_ACCESS restricted
sudo defaults write /Library/Preferences/com.beacon.endpoint BEACON_LOG_READERS ""
```

Managed preferences win over local ones, and a variable set in the install script's environment wins over both. Only the documented `BEACON_*` install settings are read, one key at a time, so nothing in the files runs, and a file is ignored with a warning unless root owns it and no other account can write it. The settings are read on every install and upgrade.

<Columns cols={2}>
  <Card title="Jamf Pro" icon="screwdriver-wrench" href="/mdm/jamf">
    Package deployment, policy scripts, validation, and Extension Attributes.
  </Card>
  <Card title="Fleet" icon="screwdriver-wrench" href="/mdm/fleet">
    Package and user-context deployment helpers.
  </Card>
  <Card title="Rippling" icon="screwdriver-wrench" href="/mdm/rippling">
    Package deployment through Rippling MDM.
  </Card>
  <Card title="All MDM options" icon="list" href="/mdm">
    Compare the supported management paths.
  </Card>
</Columns>

## Managing the service

The collector is an ordinary launchd job:

```bash title="User mode"
launchctl print "gui/$(id -u)/com.beacon.endpoint.collector.user"
```

```bash title="System mode"
sudo launchctl print system/com.beacon.endpoint.collector
```

`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:

```bash title="Repair"
beacon endpoint doctor --fix
```

### Home directory on an external volume

launchd will not bootstrap a LaunchAgent whose plist is on a volume other than the startup volume. When your home directory is on an external disk (`/Volumes/<disk>`), `launchctl bootstrap gui/<uid> ~/Library/LaunchAgents/<label>.plist` fails with `Bootstrap failed: 5: Input/output error`, even with ownership enabled on the volume.

A user-mode install handles the current login session itself. Beacon still writes the canonical plists to `~/Library/LaunchAgents`, but when that directory is on a different volume from `/Users`, it copies each plist into a private directory on the startup volume and bootstraps the copy instead. That directory is `$TMPDIR/beacon-launchd-<uid>`, with `/private/tmp/beacon-launchd-<uid>` as a fallback, and it must be owned by you with mode `0700`. This applies to the collector, the scheduled inventory job, the scheduled session sync job when it is on, and the managed forwarder. The program, its config, and the logs stay where they are, and a home on the startup volume is bootstrapped in place as before. `launchctl print "gui/$(id -u)/com.beacon.endpoint.collector.user"` shows the staged path.

The explicit bootstrap registration belongs to the current launchd login domain. Beacon cannot guarantee that launchd will reload the canonical external-volume plists automatically after logout or restart. `beacon endpoint doctor` therefore reports this layout as a medium-severity `launch_agents_volume` warning even when staging works. If the collector is not running after a restart or login, run `beacon endpoint repair --user`, which stages fresh copies and bootstraps them again. If Beacon cannot safely create and write the staging directory, doctor reports a failure with the rejected path and reason. In that case, bootstrap the plists by hand:

```bash title="Manual bootstrap from the startup volume"
beacon endpoint install --user --no-start
mkdir -p "$TMPDIR/beacon-launchd"
chmod 700 "$TMPDIR/beacon-launchd"
for label in com.beacon.endpoint.collector.user com.beacon.endpoint.inventory; do
  cp "$HOME/Library/LaunchAgents/$label.plist" "$TMPDIR/beacon-launchd/"
  launchctl bootout "gui/$(id -u)/$label" 2>/dev/null || true
  launchctl bootstrap "gui/$(id -u)" "$TMPDIR/beacon-launchd/$label.plist"
done
```

## What is macOS-specific

Most of Beacon behaves identically everywhere: the event schema, the collector, hooks, the dashboard, and threat detection. These are the parts that do not:

| Area | On macOS |
|---|---|
| Service manager | launchd. A LaunchAgent in user mode, a LaunchDaemon in system mode |
| System config | `/Library/Application Support/Beacon/Endpoint` |
| Service definition | `~/Library/LaunchAgents/com.beacon.endpoint.collector.user.plist`, or `/Library/LaunchDaemons/com.beacon.endpoint.collector.plist` |
| Package | Signed, notarized, and stapled `.pkg`, Apple Silicon |
| Update verification | SHA-256 **plus** Apple notarization |
| Fleet management | Jamf, Fleet, and Rippling assets ship in the package |
| Log forwarding helpers | Bundled Vector helpers for Falcon, S3, and GCS |

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](/platforms/linux) for how that platform differs.

## Updates

Upgrade the CLI with Homebrew, or let Beacon update a package install in place:

```bash title="Update in place"
sudo beacon endpoint update --check
sudo beacon endpoint update --apply
```

`--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 update && brew upgrade beacon`.

## Uninstall

```bash title="Remove the endpoint"
beacon endpoint uninstall            # user mode
sudo beacon endpoint uninstall --system
```

`--keep-logs` and `--keep-config` are available if you want to keep either.

## Related

<Columns cols={2}>
  <Card title="Endpoint install" icon="download" href="/cli/endpoint-install">
    All install flags, harness selection, and hook installation.
  </Card>
  <Card title="Endpoint paths and ports" icon="folder-tree" href="/cli/endpoint-paths">
    Where Beacon writes config, logs, and service definitions on each platform.
  </Card>
  <Card title="Endpoint status" icon="circle-info" href="/cli/endpoint-status">
    Inspect collector health, runtime log state, harnesses, and diagnostics.
  </Card>
  <Card title="Local dashboard" icon="chart-line" href="/cli/dashboard">
    Browse captured sessions, timelines, and event detail locally.
  </Card>
</Columns>