> ## Documentation Index
> Fetch the complete documentation index at: https://docs.asymptotelabs.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Fleet

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

To see what the package does on a single Mac before you involve Fleet, see [Try Beacon on One Mac](/mdm/try-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](/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 theme={null}
/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.

<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 theme={null}
#!/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 theme={null}
#!/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 theme={null}
    ls /opt/beacon/bin/beacon
    pkgutil --pkg-info ai.asymptote.beacon.endpoint
    ```
  </Accordion>

  <Accordion title="Beacon: collector running fails">
    ```bash theme={null}
    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 theme={null}
    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 theme={null}
    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 theme={null}
    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>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.