Skip to main content

​
Overview

Fleet can deploy and inventory the local Beacon endpoint agent on managed Macs. Beacon’s Fleet support uses the signed and notarized macOS .pkg as Fleet software, while the endpoint agent writes local JSONL telemetry without requiring a hosted account, remote policy fetch, or Fleet API credentials.

​
What Fleet manages

​
Package layout

The macOS package includes Beacon binaries, endpoint helper scripts, and Fleet assets:
The package postinstall performs the default system install. That install creates system configuration and runtime state:

​
Requirements and caveats

  • Fleet Premium. Custom software packages are a Premium feature and must be added to a specific team. They cannot be added to All teams.
  • Apple Silicon only. The signed, notarized endpoint .pkg (BeaconEndpointAgent-<version>-arm64.pkg) is arm64. Intel Macs are not covered by that artifact.
  • Scripts enabled on fleetd. Software install and Fleet scripts require fleetd --enable-scripts. Scripts are enabled by default when you use Fleet MDM.
  • Self-hosted package storage. If you self-host Fleet, configure an S3 bucket for Fleet to store uploaded installers and raise load-balancer timeouts to at least five minutes for package upload.
  • Do not put S3 or self-update enablement in the package post-install script. If a Fleet post-install script exits non-zero, fleetd uninstalls the package. Enable self-updates and S3 forwarding with separate Fleet scripts after install.
  • Self-updates are off by default and apply only to the Apple Silicon system package install. Endpoints need network access to the GitHub release manifest unless you set BEACON_UPDATE_MANIFEST_URL.
  • S3 forwarding reuses the packaged Vector helper at /opt/beacon/jamf/claude/s3/install-forwarder.sh. There is no separate Fleet-only forwarder binary. Release packages include /opt/beacon/bin/vector.
  • Fleet’s default .pkg uninstall only removes .app bundles. Beacon lives under /opt/beacon, so supply a custom uninstall script that calls the packaged cleanup helper.
For S3 forwarding plus self-updates, follow Beacon with Fleet and S3.

​
Deploy with Fleet

Upload the signed and notarized .pkg as Fleet software and scope it to a pilot team or label. The package postinstall performs the default system install, so no post-install script is required for the common deployment path. See Deploy software for Fleet’s package, script, and targeting model.
1

Upload the Beacon package

Upload the signed and notarized Beacon macOS package as Fleet software. The package installs Beacon binaries under /opt/beacon and includes Fleet helper scripts and inventory queries.
2

Scope to a pilot

Scope the software to a pilot team or label before broader rollout.
3

Add policies or labels

Add queries from /opt/beacon/fleet/queries as Fleet policies or labels to track install state, service health, log freshness, config state, and runtime log writability.
4

Optionally enable endpoint self-updates

Beacon package self-updates are off by default. To opt in during rollout, add a Fleet script or policy command that runs one of the following after the package install completes:
Enable automatic package self-updates
For visibility without automatic package installation, enable check-only mode instead:
Enable check-only update monitoring
Both commands require root and are intended for the system package install. auto mode installs newer compatible signed packages from the release manifest after package verification and health checks. check-only mode writes local update status events to /var/log/beacon-agent/system.jsonl but does not download or apply packages.
5

Optionally configure S3 forwarding

After the package is installed, run a Fleet script that starts Vector forwarding. Do not put that script in the package post-install. See Beacon with Fleet and S3.
6

Validate the deployment

Run the Fleet validation helper on a managed Mac:

​
Fleet scripts

Fleet scripts are installed under /opt/beacon/fleet/scripts: Use the install script when a workflow needs explicit parameters or a reinstall action. Fleet install script positional arguments:
Fleet repair script positional arguments:

​
Inventory with queries

Add queries from /opt/beacon/fleet/queries as Fleet policies or labels. They cover package, service, log, and config presence and freshness. Available queries:
  • beacon-version.sql
  • collector-service-health.sql
  • last-event-age-seconds.sql
  • configured-harnesses.sql
  • runtime-log-writable.sql
  • splunk-hec-forwarding.sql
  • falcon-vector-forwarder-health.sql
  • s3-vector-forwarder-health.sql
  • s3-vector-forwarding-configured.sql
Recommended Fleet policies:
  • Beacon install state is not not_installed.
  • Collector service health is running.
  • Last runtime event age is less than 86400.
  • Endpoint config state is present.
  • Runtime log state is present.
  • Splunk HEC config state is configured when HEC export is required.
  • S3 Vector forwarder health is running when S3 forwarding is required.
  • S3 Vector forwarding state is configured when S3 forwarding is required.

​
Repair and uninstall

Use /opt/beacon/fleet/scripts/repair.sh for endpoints where policies report a stale or unhealthy install. Include gemini in the harness argument, for example claude,codex,gemini, when the repair workflow should manage Gemini CLI telemetry settings. Configure GitHub Copilot CLI separately by deploying COPILOT_OTEL_ENABLED=true and OTEL_EXPORTER_OTLP_ENDPOINT=http://127.0.0.1:4318 in Copilot’s launch environment. Use /opt/beacon/fleet/scripts/uninstall.sh to remove endpoint service files. Set BEACON_KEEP_LOGS=1 or the first uninstall argument to preserve runtime logs during removal. Set BEACON_KEEP_CONFIG=1 or the second uninstall argument to preserve harness telemetry configuration.

​
Troubleshooting

If the Beacon version query reports not_installed, confirm the Fleet software install completed and that the package is scoped to the host.On the device, verify that the expected files exist:
Check endpoint status and launchd state:
If the service file or collector configuration drifted, run /opt/beacon/fleet/scripts/repair.sh.
Verify that the runtime log exists and is writable:
If validation succeeds but events remain stale, confirm the configured harnesses match the agent harnesses installed or configured for the device and that the local collector ports are not in use by another process. For GitHub Copilot CLI, confirm Copilot’s launch environment includes COPILOT_OTEL_ENABLED=true and points OTLP HTTP at the local Beacon collector.
Check Fleet install script arguments 6 and 7, or the BEACON_SPLUNK_HEC_ENDPOINT and BEACON_SPLUNK_HEC_TOKEN environment variables used by the install workflow.Use splunk-hec-forwarding.sql to verify whether endpoint configuration contains a Splunk destination. On the device, confirm the non-secret destination fields:
Check update mode, launchd state, and local system update events:
If the updater is disabled or missing, run the Fleet script or policy command that enables the desired mode:
To trigger an urgent update check from Fleet, run the scheduled updater path immediately:
Confirm the release package includes Vector and that the Fleet S3 script ran after install:
If the environment file is missing, rerun beacon-configure-s3-forwarding.sh from Fleet. Do not echo AWS secrets in script output. Vector batches uploads for up to five minutes.

Beacon with Fleet and S3

Upload the package, enable self-updates, and forward runtime plus inventory JSONL to S3.

MDM deployment

Review the shared macOS MDM deployment model and package layout.

Log forwarding

Forward Beacon events into Wazuh, Splunk HEC, Falcon LogScale, Elastic, Datadog, Sumo Logic, Rapid7 InsightIDR, or customer-managed pipelines.