Fleet

Fleet installs Beacon on your Macs as a custom package. Beacon then runs locally, writing agent activity to /var/log/beacon-agent/runtime.jsonl, and needs no Beacon account and no Fleet API access on the Mac.

Beacon with Fleet and S3

Start here. A step-by-step rollout from a pilot Mac to every Mac, including forwarding to your own S3 bucket.

To see what the package does on a single Mac before you involve Fleet, see Try Beacon on One Mac. This page is the reference for what the package gives Fleet admins.

Requirements

Fleet Premium and a specific team. Custom packages can’t be added to “All teams”. Fleet 4.82 and later call teams fleets.
Apple Silicon Macs. The signed package, BeaconEndpointAgent-<version>-arm64.pkg, is Apple Silicon only. Set the package’s Pre-install query to SELECT 1 FROM system_info WHERE cpu_type LIKE 'arm64%'; so Fleet skips Intel Macs.
Scripts enabled in fleetd. This is the default with Fleet MDM. Otherwise deploy fleetd with --enable-scripts.
A custom uninstall script. Fleet’s default .pkg uninstall only removes .app bundles. Use the one in the guide, which runs Beacon’s full cleanup.
Nothing in the post-install script. If a Fleet post-install script fails, fleetd uninstalls the package. Run S3 setup and self-update setup as separate scripts after the install.
Leave the package’s Deploy switch off. Fleet 4.83 and later call automatic install Deploy. For a .pkg, the policy it creates checks for an app bundle to decide whether the package is installed, and Beacon has none, so that policy never passes. Use the Beacon: installed policy with an Install software automation instead.

What the package installs

The package postinstall runs a system-mode install and configures Claude Code and Codex for the user logged in at the Mac.

/opt/beacon/bin/beacon, beacon-otelcol, vector
/opt/beacon/fleet/policies/*.sql     Fleet policies
/opt/beacon/fleet/queries/*.sql      Fleet reports
/opt/beacon/fleet/scripts/*.sh       install, repair, validate, uninstall
/Library/Application Support/Beacon/Endpoint/config.json
/Library/LaunchDaemons/com.beacon.endpoint.collector.plist
/Library/LaunchDaemons/com.beacon.endpoint.inventory.plist
/var/log/beacon-agent/runtime.jsonl
/var/log/beacon-agent/inventory_state.jsonl

Policies and reports

The package ships two kinds of osquery files. Policies (/opt/beacon/fleet/policies) return a row only when that part of Beacon is healthy, so a failing policy points at a problem. They all pass on Intel Macs, where the package doesn’t apply.

File	Passes when
`beacon-installed.sql`	The package receipt and `/opt/beacon/bin/beacon` are present
`collector-running.sql`	The collector process is running as root
`s3-forwarder-running.sql`	Vector is running with Beacon’s S3 config
`s3-forwarding-configured.sql`	The S3 credentials file, Vector config, and LaunchDaemon are all present
`inventory-heartbeat-recent.sql`	Inventory was written in the last 96 hours

Reports (/opt/beacon/fleet/queries) return one row per host with a status value, for dashboards and exports: install state and version, collector health, S3 and Falcon forwarder health, S3 configuration, inventory heartbeat age, last event age, config presence, runtime log presence, and Splunk HEC configuration.

Don’t turn reports into policies. A report returns a row on every host, and Fleet passes a policy whenever its query returns a row, so the policy always passes. Policies built from these files before the policies/ folder existed have this problem, and three of them also read a launchd column that osquery doesn’t have. Replace them with the files in policies/.

The admin helper creates the five policies and the main reports for you.

Fleet scripts

These are in /opt/beacon/fleet/scripts on each Mac:

Script	What it does
`install.sh`	Runs the system install again, for example with different agents
`repair.sh`	Repairs the collector and agent settings. Keeps logs, config, and any S3 forwarder.
`validate.sh`	Prints endpoint status and LaunchDaemon health
`uninstall.sh`	Removes the endpoint service, its config, and the S3, GCS, and Falcon forwarders with their credentials. It leaves `/opt/beacon` and the package receipt. For a complete removal, uninstall the package from Fleet.

Fleet runs scripts without arguments, so pass settings as environment variables in a short wrapper script. For example, to add Gemini CLI:

#!/bin/sh
BEACON_ENDPOINT_HARNESSES=claude,codex,gemini /opt/beacon/fleet/scripts/repair.sh

Variable	Used by	Default
`BEACON_ENDPOINT_HARNESSES`	`install.sh`, `repair.sh`	`claude,codex`
`BEACON_OTLP_GRPC_PORT`, `BEACON_OTLP_HTTP_PORT`	`install.sh`, `repair.sh`	`4317`, `4318`
`BEACON_SPLUNK_HEC_ENDPOINT`, `BEACON_SPLUNK_HEC_TOKEN`	`install.sh`, `repair.sh`	none
`BEACON_KEEP_LOGS=1`, `BEACON_KEEP_CONFIG=1`	`uninstall.sh`	off

GitHub Copilot CLI isn’t in the agent list. Deploy COPILOT_OTEL_ENABLED=true and OTEL_EXPORTER_OTLP_ENDPOINT=http://127.0.0.1:4318 in Copilot’s launch environment instead.

Self-updates

Self-updates are off by default. Turn them on with a Fleet script after the package is installed:

#!/bin/sh
/opt/beacon/bin/beacon endpoint update enable            # or: update enable --check-only

auto mode installs newer signed packages after verifying them, and rolls back if the new version fails its health check. check-only only records that an update is available, in /var/log/beacon-agent/system.jsonl. Macs need to reach GitHub Releases. To use a release manifest you host, write {"manifest_url": "https://..."} to /Library/Application Support/Beacon/Endpoint/managed.json.

Troubleshooting

Beacon: installed fails

Check that the package is scoped to the host and that the install finished in the host’s Activity tab. On the Mac:

ls /opt/beacon/bin/beacon
pkgutil --pkg-info ai.asymptote.beacon.endpoint

Beacon: collector running fails

sudo /opt/beacon/bin/beacon endpoint status --system
sudo /opt/beacon/bin/beacon endpoint doctor --system

doctor prints the command that fixes anything it finds. /opt/beacon/fleet/scripts/repair.sh also repairs the collector without touching logs or forwarding.

No agent activity from a Mac

The package only configures the user logged in when it installed. After that user logs in, run:

sudo /opt/beacon/bin/beacon endpoint user-config repair-installed --system

Agent sessions that were already open keep their old settings, so start a new one.

S3 forwarding

See Troubleshooting in the Fleet and S3 guide.

Splunk HEC isn't configured

Check that the install or repair wrapper sets BEACON_SPLUNK_HEC_ENDPOINT and BEACON_SPLUNK_HEC_TOKEN. On the Mac, sudo /opt/beacon/bin/beacon endpoint status --system --json shows the configured destination without the token.

Self-updates aren't running

sudo /opt/beacon/bin/beacon endpoint update status
sudo tail -n 30 /var/log/beacon-agent/system.jsonl

Update mode: off means the enable script hasn’t run on this Mac. To check for an update right away:

sudo BEACON_UPDATE_JITTER_SECONDS=0 /opt/beacon/bin/beacon endpoint update --scheduled

Beacon with Fleet and S3

The step-by-step rollout, including S3 forwarding.

MDM deployment

The macOS package and how it behaves under any MDM.

Log forwarding

Other destinations: Splunk HEC, Falcon LogScale, Elastic, Sentinel, and more.

Get Started

Deploy Asymptote

How Asymptote Works

Manage Asymptote

Agent Harness Integrations

For Security & IT Teams

Support

Contributing

Beacon with Fleet and S3

Requirements

What the package installs

Policies and reports

Fleet scripts

Self-updates

Troubleshooting

Beacon with Fleet and S3

MDM deployment

Log forwarding

Beacon with Fleet and S3

​Requirements

​What the package installs

​Policies and reports

​Fleet scripts

​Self-updates

​Troubleshooting

​Related

Beacon with Fleet and S3

MDM deployment

Log forwarding

Requirements

What the package installs

Policies and reports

Fleet scripts

Self-updates

Troubleshooting

Related