The cross-harness, self-improving memory layer for AI agents. Join our community: https://discord.com/invite/zdNChS2fBu
Go agent-ai-cliagent-harnessesagent-securitybrowser-extensionciclaude-codecloudcodexcursordetection-engineeringjevknowledge-basememorymobile-device-managementobservabilitysecuritysecurity-information-and-event-managementsecurity-toolstelemetrytraces
---
title: "Fleet"
description: "Deploy the Beacon endpoint agent to Macs with Fleet, and reference for the Fleet scripts, policies, and reports it ships."
---
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.
<Card title="Beacon with Fleet and S3" icon="bucket" href="/guides/fleet-s3-mdm">
Start here. A step-by-step rollout from a pilot Mac to every Mac, including forwarding to your own S3 bucket.
</Card>
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](/guides/fleet-s3-mdm#3-set-up-fleet), 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.
```text
/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
/Library/LaunchDaemons/com.beacon.endpoint.session-sync.plist only with session sync on
/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.
<Warning>
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/`.
</Warning>
The [admin helper](/guides/fleet-s3-mdm#3-set-up-fleet) 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:
```bash
#!/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:
```bash
#!/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
<AccordionGroup>
<Accordion title="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:
```bash
ls /opt/beacon/bin/beacon
pkgutil --pkg-info ai.asymptote.beacon.endpoint
```
</Accordion>
<Accordion title="Beacon: collector running fails">
```bash
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.
</Accordion>
<Accordion title="No agent activity from a Mac">
The package only configures the user logged in when it installed. After that user logs in, run:
```bash
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.
</Accordion>
<Accordion title="S3 forwarding">
See [Troubleshooting in the Fleet and S3 guide](/guides/fleet-s3-mdm#troubleshooting).
</Accordion>
<Accordion title="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.
</Accordion>
<Accordion title="Self-updates aren't running">
```bash
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:
```bash
sudo BEACON_UPDATE_JITTER_SECONDS=0 /opt/beacon/bin/beacon endpoint update --scheduled
```
</Accordion>
</AccordionGroup>
## Related
<Columns cols={2}>
<Card title="Beacon with Fleet and S3" icon="bucket" href="/guides/fleet-s3-mdm">
The step-by-step rollout, including S3 forwarding.
</Card>
<Card title="MDM deployment" icon="laptop-mobile" href="/mdm">
The macOS package and how it behaves under any MDM.
</Card>
<Card title="Log forwarding" icon="tower-broadcast" href="/log-forwarding">
Other destinations: Splunk HEC, Falcon LogScale, Elastic, Sentinel, and more.
</Card>
</Columns>