Skip to content

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

docs: rewrite the Fleet and S3 rollout guide

shukieshahb121e918460e
diff --git a/docs/cli/endpoint-uninstall.mdx b/docs/cli/endpoint-uninstall.mdx
index a25c1bd7..5eb003f5 100644
--- a/docs/cli/endpoint-uninstall.mdx
+++ b/docs/cli/endpoint-uninstall.mdx
@@ -59,6 +59,8 @@ sudo beacon endpoint uninstall --system --keep-logs
Beacon removes files listed in its install manifest, including managed config, collector config, and service files. Unless `--keep-logs` is set, it also removes the configured runtime JSONL log.
+On a macOS system install, uninstall also stops and removes the S3, GCS, and Falcon forwarders that the package's MDM helpers install (`com.beacon.endpoint.s3-forwarder`, `gcs-forwarder`, and `falcon-forwarder`). Unless `--keep-config` is set, it deletes `/Library/Application Support/Beacon/Forwarders`, which holds their credentials. `beacon endpoint repair` leaves these forwarders running.
+
If the endpoint was connected to Beacon managed ingest, uninstall also stops and removes the `com.beacon.endpoint.asymptote-forwarder` service (or `beacon-asymptote-forwarder.service`) and the `asymptote/` directory holding the Vector config, buffer, enrollment record and device key; `--keep-config` keeps the enrollment record and key. The device stays registered server-side until it is revoked from the dashboard's Beacon Endpoints page.
## Related
diff --git a/docs/cli/s3.mdx b/docs/cli/s3.mdx
index 533de104..09065f25 100644
--- a/docs/cli/s3.mdx
+++ b/docs/cli/s3.mdx
@@ -17,7 +17,7 @@ beacon endpoint s3 [command]
<Columns cols={2}>
<Card title="beacon endpoint s3 print-config" icon="file-lines" href="#beacon-endpoint-s3-print-config">
- Print the Vector AWS S3 forwarding template for the configured runtime log.
+ Print a one-shot AWS CLI script that uploads the current logs to S3.
</Card>
<Card title="beacon endpoint s3 install-pack" icon="box-archive" href="#beacon-endpoint-s3-install-pack">
Write AWS S3 forwarding content to a directory.
@@ -36,31 +36,29 @@ beacon endpoint s3 [command]
## beacon endpoint s3 print-config
-`beacon endpoint s3 print-config` prints a Vector configuration that tails the selected Beacon runtime JSONL log and writes gzip-compressed NDJSON objects to AWS S3.
+`beacon endpoint s3 print-config` prints a smoke-test script. The script uses the AWS CLI to copy the current runtime and inventory logs, once, to `<prefix>/runtime/smoke-tests/` and `<prefix>/inventory/smoke-tests/` in your bucket. Use it to check bucket access and IAM before you set up continuous forwarding. For the Vector configuration, use [`install-pack`](#beacon-endpoint-s3-install-pack).
-```bash title="Print the configuration"
+```bash title="Print the smoke-test script"
beacon endpoint s3 print-config
```
-Use this command when you want to inspect or copy the Vector template into an existing endpoint forwarding workflow.
-
### Examples
-Print Vector config for the default per-user Beacon install:
+Print the script for the default per-user Beacon install:
-```bash title="Print Vector config for the default per-user Beacon install"
+```bash title="Print the script for the default per-user Beacon install"
beacon endpoint s3 print-config
```
-Print Vector config for a system-mode MDM deployment:
+Print the script for a system-mode MDM deployment:
-```bash title="Print Vector config for a system-mode MDM deployment"
+```bash title="Print the script for a system-mode MDM deployment"
sudo /opt/beacon/bin/beacon endpoint s3 print-config --system
```
-Print Vector config for a custom runtime log:
+Print the script for a custom runtime log:
-```bash title="Print Vector config for a custom runtime log"
+```bash title="Print the script for a custom runtime log"
beacon endpoint s3 print-config --log-path /path/to/runtime.jsonl
```
@@ -86,7 +84,9 @@ The generated Vector template preserves each Beacon event's canonical
`gen_ai.usage` payload and also flattens token and runtime-reported cost fields
to top-level JSON columns for downstream analytics: `input_tokens`,
`output_tokens`, `cache_read_input_tokens`, `cache_creation_input_tokens`,
-`reasoning_output_tokens`, and `cost_usd`.
+`reasoning_output_tokens`, and `cost_usd`. The packaged macOS S3 forwarder that
+MDM deployments use doesn't add these columns; its objects carry `gen_ai.usage`
+only.
### Examples
@@ -149,10 +149,10 @@ Write a validation event to a custom runtime log:
beacon endpoint s3 validate --log-path /path/to/runtime.jsonl
```
-The validation command writes the local event only. Confirm remote delivery with AWS tooling:
+The validation command writes the local event only. The forwarder uploads in batches, so allow up to five minutes, then confirm delivery with AWS tooling. The event lands under `runtime/`:
```text
-aws s3 ls "s3://${BEACON_S3_BUCKET}/${BEACON_S3_PREFIX}/" --recursive --region "$AWS_REGION"
+aws s3 ls "s3://${BEACON_S3_BUCKET}/${BEACON_S3_PREFIX}/runtime/" --recursive --region "$AWS_REGION"
aws s3 cp "s3://${BEACON_S3_BUCKET}/${BEACON_S3_PREFIX}/runtime/date=<date>/<object>.jsonl.gz" - --region "$AWS_REGION" | gzip -dc | grep "Beacon endpoint S3 validation event"
```
diff --git a/docs/guides/fleet-s3-mdm.mdx b/docs/guides/fleet-s3-mdm.mdx
index 06465224..dfc7663a 100644
--- a/docs/guides/fleet-s3-mdm.mdx
+++ b/docs/guides/fleet-s3-mdm.mdx
@@ -1,72 +1,87 @@
---
title: "Beacon with Fleet and S3"
-description: "Install Beacon on Apple Silicon Macs with Fleet, enable self-updates, and forward runtime and inventory telemetry to AWS S3."
+description: "Roll out Beacon to Apple Silicon Macs with Fleet and send runtime and inventory telemetry to your own S3 bucket."
---
-## Overview
+This guide takes you from no Beacon on your Macs to every Mac in scope sending its AI agent activity to an S3 bucket you own. Follow the steps in order.
-Use this guide when you want Fleet to install Beacon on managed Macs and forward endpoint telemetry to a bucket you own.
+## What you'll set up
-When you are done:
+When you finish, each Mac in scope has:
-- Beacon is installed under `/opt/beacon`.
-- The collector runs as `com.beacon.endpoint.collector`.
-- Runtime events go to `/var/log/beacon-agent/runtime.jsonl`.
-- Inventory events go to `/var/log/beacon-agent/inventory_state.jsonl`.
-- Vector uploads both files to S3:
+- Beacon installed under `/opt/beacon`, with its collector running as the LaunchDaemon `com.beacon.endpoint.collector`.
+- Claude Code and Codex reporting to that collector for the user who is logged in at the Mac.
+- Agent activity written to `/var/log/beacon-agent/runtime.jsonl`, and an inventory of the Mac's agents written to `/var/log/beacon-agent/inventory_state.jsonl` every 6 hours.
+- A forwarder (Vector, shipped in the package) uploading both files to your bucket:
```text
-s3://<bucket>/<prefix>/runtime/date=YYYY-MM-DD/<object>.jsonl.gz
-s3://<bucket>/<prefix>/inventory/date=YYYY-MM-DD/<object>.jsonl.gz
+s3://<bucket>/<prefix>/runtime/date=YYYY-MM-DD/<time>-<id>.jsonl.gz
+s3://<bucket>/<prefix>/inventory/date=YYYY-MM-DD/<time>-<id>.jsonl.gz
```
+Fleet shows each part's health per host through five policies.
+
```mermaid
flowchart LR
- Admin[Admin helper or Fleet UI] --> Pkg[Beacon pkg]
- Admin --> Scripts[Fleet scripts]
- Pkg --> Beacon["/opt/beacon"]
- Beacon --> Collector[Endpoint collector]
- Collector --> Runtime["runtime.jsonl"]
- Collector --> Inventory["inventory_state.jsonl"]
- Scripts --> Updates[Self-update LaunchDaemon]
- Scripts --> Vector[S3 Vector LaunchDaemon]
- Runtime --> Vector
- Inventory --> Vector
- Vector --> S3[AWS S3]
+ Fleet[Fleet] -->|installs| Pkg[Beacon package]
+ Fleet -->|runs script| Fwd[S3 forwarder]
+ Pkg --> Collector[Beacon collector]
+ Agents[Claude Code, Codex] --> Collector
+ Collector --> Logs["runtime.jsonl, inventory_state.jsonl"]
+ Logs --> Fwd
+ Fwd --> S3[(Your S3 bucket)]
```
-Start with the admin helper in this repo unless you would rather click through the Fleet UI. The helper talks to your Fleet server once. After that, you install the package on a pilot Mac and run two scripts.
-
## Before you start
-You need:
+| You need | Why |
+| --- | --- |
+| Fleet Premium, version 4.62 or later | Custom packages and secret variables are Premium features. |
+| A pilot team in Fleet with a few test Macs | Custom packages can't be added to "All teams". Fleet 4.82 and later call teams *fleets*; this guide says *team*. |
+| Apple Silicon Macs | The signed Beacon package is Apple Silicon only. |
+| Scripts enabled in `fleetd` | On by default when you use Fleet MDM. Otherwise deploy `fleetd` with `--enable-scripts`. |
+| An AWS account where you can create an S3 bucket and an IAM user | Step 2. |
+| For the admin helper only: a Fleet API token with the global admin or maintainer role, and `curl` and `python3` on your workstation | Only a global role can store the AWS keys as Fleet secret variables. See [Create the API token](#create-the-api-token). |
+
+The Macs don't need Beacon installed beforehand. Fleet installs it in step 4.
+
+<Note>
+ If you self-host Fleet, it needs its own storage for uploaded packages, separate from the telemetry bucket in this guide. Set load balancer timeouts to at least five minutes so the package upload doesn't time out.
+</Note>
+
+## 1. Try Beacon on one Mac (optional)
+
+To see what the package does before involving Fleet, install it by hand on one Apple Silicon Mac. This install needs no account and sends nothing off the Mac. Run it in Terminal while logged in at the Mac:
+
+```bash title="Download, verify, and install"
+VERSION="$(curl -fsSLI -o /dev/null -w '%{url_effective}' https://github.com/asymptote-labs/agent-beacon/releases/latest)"; VERSION="${VERSION##*/v}"
+PKG="BeaconEndpointAgent-${VERSION}-arm64.pkg"
+BASE="https://github.com/asymptote-labs/agent-beacon/releases/download/v${VERSION}"
+curl -fsSLO "${BASE}/${PKG}" && curl -fsSLO "${BASE}/${PKG}.sha256"
+test "$(awk '{print $1}' "${PKG}.sha256")" = "$(shasum -a 256 "${PKG}" | awk '{print $1}')" \
+ && pkgutil --check-signature "${PKG}" \
+ && sudo installer -pkg "${PKG}" -target /
+```
-- [Fleet Premium](https://fleetdm.com/guides/deploy-software-packages). Custom packages cannot be added to All teams.
-- A Fleet team for the pilot, not All teams.
-- `fleetd` with scripts enabled. That is the default when you use Fleet MDM. Otherwise deploy `fleetd` with `--enable-scripts`.
-- Apple Silicon Macs. The signed Beacon package is `BeaconEndpointAgent-<version>-arm64.pkg`.
-- An API token that can manage software, scripts, and variables on that team.
-- An S3 bucket and an IAM principal that can `s3:PutObject` on one prefix in that bucket.
-- `curl` and `python3` on the machine that runs the helper.
+The block checks the package against its published SHA-256 and its Apple signature before installing. `pkgutil` should print `Status: signed by a developer certificate issued by Apple for distribution`.
-If you self-host Fleet, Fleet also needs its own S3 bucket to store uploaded installers. That bucket is separate from the telemetry bucket in this guide. Raise load-balancer timeouts to at least five minutes so the package upload does not time out.
+Then check it:
-<Warning>
- Do not put self-update or S3 setup in the software package's post-install script. If that script fails, Fleet uninstalls Beacon.
-</Warning>
+```bash
+sudo /opt/beacon/bin/beacon endpoint status --system
+```
-## 1. Prepare the S3 prefix and IAM
+`Service: loaded=true running=true` and `telemetry=enabled` next to Claude Code and Codex mean it's working. Start a new Claude Code session and its activity appears in `/var/log/beacon-agent/runtime.jsonl`.
-Pick a root prefix such as `beacon` or `beacon-prod`. Do not put `runtime` or `inventory` in the prefix. Beacon adds those folders itself:
+You can leave this Mac as it is. When Fleet installs the same package on it later, the install is simply repeated.
-```bash
-BEACON_S3_PREFIX="beacon-prod" # good
-BEACON_S3_PREFIX="beacon-prod/runtime" # avoid
-```
+## 2. Prepare S3
-Grant the writer `s3:PutObject` on that prefix only:
+**Pick a prefix** such as `beacon-prod`. Beacon adds `runtime/` and `inventory/` under it, so don't put either in the prefix.
-```json
+**Create an IAM user for Beacon** with this policy. Replace the bucket and prefix with yours:
+
+```json title="IAM policy for the Beacon writer"
{
"Version": "2012-10-17",
"Statement": [
@@ -79,319 +94,456 @@ Grant the writer `s3:PutObject` on that prefix only:
}
```
-Beacon does not store AWS credentials in endpoint config. The packaged Vector helper writes provider-chain values into a root-owned file:
-
-```text
-/Library/Application Support/Beacon/Forwarders/s3-vector.env
-```
-
-That file is mode `0600`. Vector reads it when the LaunchDaemon starts.
-
-## 2. Run the admin helper
-
-The helper runs on your workstation. It does not run on the Macs.
-
-Download it from the repo:
-
-```bash
-curl -fsSL -o configure-beacon-macos-s3.sh \
- https://raw.githubusercontent.com/asymptote-labs/agent-beacon/main/examples/fleet/configure-beacon-macos-s3.sh
-chmod +x configure-beacon-macos-s3.sh
-```
-
-Or copy `examples/fleet/configure-beacon-macos-s3.sh` from a clone.
+**Create an access key** for that user. Use a long-lived key, which starts with `AKIA`. Temporary credentials stop working when they expire, and uploads that fail after that point are lost.
-Preview the host scripts without calling Fleet:
+Three things about the bucket:
+
+- **Startup check.** When the forwarder starts, it checks that it can reach the bucket, which needs `s3:ListBucket` on `arn:aws:s3:::example-security-logs`. Without it, uploads still work, but the forwarder's log shows a health-check error at startup. Add the permission if you'd rather not see that error.
+- **KMS.** If the bucket's default encryption uses a customer managed KMS key, also allow `kms:GenerateDataKey` on that key.
+- **Encryption headers.** Beacon doesn't send encryption headers or ACLs, so the bucket's default encryption applies. A bucket policy that requires an encryption header on every upload will reject Beacon's uploads.
+
+## 3. Set up Fleet
+
+Both options end in the same place: the Beacon package, the AWS keys, three scripts, and five health policies in your pilot team.
+
+<Tabs>
+ <Tab title="Admin helper (recommended)">
+ The helper runs once on your workstation and makes all the Fleet changes for you. It checks your token's role before changing anything.
+
+ **Download it:**
+
+ ```bash
+ curl -fsSL -o configure-beacon-macos-s3.sh \
+ https://raw.githubusercontent.com/asymptote-labs/agent-beacon/main/examples/fleet/configure-beacon-macos-s3.sh
+ chmod +x configure-beacon-macos-s3.sh
+ ```
+
+ **Preview it.** This prints the plan and the scripts it would create, and makes no network calls:
+
+ ```bash
+ BEACON_S3_BUCKET="example-security-logs" \
+ AWS_REGION="us-west-2" \
+ BEACON_S3_PREFIX="beacon-prod" \
+ ./configure-beacon-macos-s3.sh --yes --dry-run
+ ```
+
+ **Run it:**
+
+ ```bash
+ ./configure-beacon-macos-s3.sh
+ ```
+
+ It asks for:
+
+ | Prompt | What to enter |
+ | --- | --- |
+ | Fleet URL | `https://fleet.example.com` |
+ | Fleet API token | The global admin or maintainer token |
+ | Install Beacon automatically on every Mac in this team? | `n` for now. You turn this on in step 6. |
+ | S3 bucket, AWS region, S3 prefix | From step 2 |
+ | S3 storage class | Press Enter for `STANDARD` |
+ | AWS credentials | `k` for a key pair |
+ | Access key ID and secret access key | The key from step 2. The secret is asked twice. |
+ | Session token | Press Enter to skip |
+ | Fleet team ID | The helper lists your teams. Pick the pilot team. |
+
+ When it finishes, your pilot team has:
+
+ - The package, named **Beacon Endpoint Agent**. It has a check that skips Intel Macs, and an uninstall script that removes Beacon completely.
+ - The AWS keys stored as Fleet secret variables.
+ - Three scripts: `beacon-configure-s3-forwarding.sh`, `beacon-enable-self-updates.sh`, and `beacon-validate.sh`.
+ - Five policies whose names start with **Beacon:**, and five reports.
+
+ You can run the helper again at any time. It changes only what's different, so rerunning it after a new Beacon release uploads the new package.
+
+ <Accordion title="Run it without prompts">
+ Set every value as an environment variable and pass `--yes`:
+
+ ```bash
+ FLEET_URL="https://fleet.example.com" \
+ FLEET_TOKEN="..." \
+ FLEET_TEAM_ID="7" \
+ BEACON_S3_BUCKET="example-security-logs" \
+ AWS_REGION="us-west-2" \
+ BEACON_S3_PREFIX="beacon-prod" \
+ AWS_ACCESS_KEY_ID="AKIA..." \
+ AWS_SECRET_ACCESS_KEY="..." \
+ ./configure-beacon-macos-s3.sh --yes
+ ```
+
+ With `--yes`, the helper stops if the AWS keys are missing, so it never sets up forwarding without credentials by accident.
+ </Accordion>
+
+ <Accordion title="If you manage Fleet with GitOps">
+ The next GitOps run can overwrite changes the helper made through the API. Either add the package, scripts, policies, and `$FLEET_SECRET_*` variables to your GitOps repo, or rerun the helper after each GitOps run.
+ </Accordion>
+ </Tab>
+
+ <Tab title="Fleet UI">
+ **1. Download and verify the package** on your workstation:
+
+ ```bash
+ VERSION="$(curl -fsSLI -o /dev/null -w '%{url_effective}' https://github.com/asymptote-labs/agent-beacon/releases/latest)"; VERSION="${VERSION##*/v}"
+ PKG="BeaconEndpointAgent-${VERSION}-arm64.pkg"
+ BASE="https://github.com/asymptote-labs/agent-beacon/releases/download/v${VERSION}"
+ curl -fsSLO "${BASE}/${PKG}" && curl -fsSLO "${BASE}/${PKG}.sha256"
+ test "$(awk '{print $1}' "${PKG}.sha256")" = "$(shasum -a 256 "${PKG}" | awk '{print $1}')" \
+ && pkgutil --check-signature "${PKG}"
+ ```
+
+ **2. Add the package.** In Fleet, go to **Software** and pick your pilot team in the team selector. Click **Add software**, open the **Custom package** tab, and choose the `.pkg` file. Then:
+
+ - Leave **Deploy** off. Step 6 explains why.
+ - Open **Advanced options**.
+ - Set **Pre-install query** to `SELECT 1 FROM system_info WHERE cpu_type LIKE 'arm64%';`. This skips Intel Macs.
+ - Replace the **Uninstall script** with the script below. Fleet's default only removes `.app` bundles, and Beacon has none.
+ - Leave **Install script** as the default, and leave **Post-install script** empty.
+ - Click **Add software**.
+
+ ```bash title="Uninstall script"
+ #!/bin/sh
+ set -eu
+ if [ -x /opt/beacon/jamf/scripts/full-cleanup.sh ]; then
+ /opt/beacon/jamf/scripts/full-cleanup.sh
+ elif [ -x /opt/beacon/fleet/scripts/uninstall.sh ]; then
+ /opt/beacon/fleet/scripts/uninstall.sh
+ rm -rf /opt/beacon "/Library/Application Support/Beacon" /Library/LaunchDaemons/com.beacon.endpoint.*.plist
+ pkgutil --forget "ai.asymptote.beacon.endpoint" >/dev/null 2>&1 || true
+ fi
+ ```
+
+ **3. Store the AWS keys.** Go to **Controls > Variables** and use **Add variable** to add each of these. Variables apply to every team, and only a global admin or maintainer can add them.
+
+ | Name | Value |
+ | --- | --- |
+ | `BEACON_AWS_ACCESS_KEY_ID` | The access key ID from step 2 |
+ | `BEACON_AWS_SECRET_ACCESS_KEY` | The secret access key from step 2 |
+
+ **4. Add the scripts.** Go to **Controls > Scripts**, pick the pilot team, and use **Add script** to upload each of these. Change the bucket, region, and prefix in the first one.
+
+ <Accordion title="beacon-configure-s3-forwarding.sh">
+ ```bash
+ #!/bin/sh
+ set -eu
+ # Fleet substitutes $FLEET_SECRET_* before this script reaches the Mac.
+ # Don't echo credential values: Fleet shows script output in its UI.
+ INSTALLER="${BEACON_S3_VECTOR_SCRIPT:-/opt/beacon/jamf/claude/s3/install-forwarder.sh}"
+ VECTOR="${BEACON_VECTOR_BIN:-/opt/beacon/bin/vector}"
+ if [ ! -x "$INSTALLER" ]; then
+ echo "S3 forwarder helper missing at $INSTALLER; install the Beacon package first" >&2
+ exit 1
+ fi
+ if [ ! -x "$VECTOR" ]; then
+ echo "Vector missing at $VECTOR; the Beacon package must include /opt/beacon/bin/vector" >&2
+ exit 1
+ fi
+ export BEACON_S3_BUCKET="example-security-logs"
+ export AWS_REGION="us-west-2"
+ export BEACON_S3_PREFIX="beacon-prod"
+ export BEACON_S3_STORAGE_CLASS="STANDARD"
+ export BEACON_VECTOR_READ_FROM="${BEACON_VECTOR_READ_FROM:-end}"
+ export AWS_ACCESS_KEY_ID="$FLEET_SECRET_BEACON_AWS_ACCESS_KEY_ID"
+ export AWS_SECRET_ACCESS_KEY="$FLEET_SECRET_BEACON_AWS_SECRET_ACCESS_KEY"
+ "$INSTALLER"
+ echo "S3 Vector forwarder configured. Credential values were not printed."
+ if command -v launchctl >/dev/null 2>&1; then
+ launchctl print system/com.beacon.endpoint.s3-forwarder | grep -E 'state =|pid =|last exit code' || true
+ fi
+ ```
+ </Accordion>
+
+ <Accordion title="beacon-enable-self-updates.sh">
+ ```bash
+ #!/bin/sh
+ set -eu
+ BEACON="${BEACON_BIN:-/opt/beacon/bin/beacon}"
+ if [ ! -x "$BEACON" ]; then
+ echo "Beacon is not installed at $BEACON" >&2
+ exit 1
+ fi
+ "$BEACON" endpoint update enable
+ "$BEACON" endpoint update status
+ ```
+
+ For update checks without automatic installs, change `update enable` to `update enable --check-only`.
+ </Accordion>
+
+ <Accordion title="beacon-validate.sh">
+ ```bash
+ #!/bin/sh
+ set -eu
+ BEACON="${BEACON_BIN:-/opt/beacon/bin/beacon}"
+ "$BEACON" endpoint update status || true
+ launchctl print system/com.beacon.endpoint.collector | grep -E 'state =|pid =|last exit code' || true
+ launchctl print system/com.beacon.endpoint.updater | grep -E 'state =|pid =|last exit code' || true
+ launchctl print system/com.beacon.endpoint.s3-forwarder | grep -E 'state =|pid =|last exit code' || true
+ ```
+ </Accordion>
+
+ **5. Add the health policies.** Go to **Policies**, pick the pilot team, and click **Add policy** once per file below. Paste the file's contents into **Query**, click **Save**, and give the policy the name in the table.
+
+ | Policy name | File |
+ | --- | --- |
+ | Beacon: installed | [`beacon-installed.sql`](https://github.com/asymptote-labs/agent-beacon/blob/main/packaging/macos/fleet/policies/beacon-installed.sql) |
+ | Beacon: collector running | [`collector-running.sql`](https://github.com/asymptote-labs/agent-beacon/blob/main/packaging/macos/fleet/policies/collector-running.sql) |
+ | Beacon: S3 forwarder running | [`s3-forwarder-running.sql`](https://github.com/asymptote-labs/agent-beacon/blob/main/packaging/macos/fleet/policies/s3-forwarder-running.sql) |
+ | Beacon: S3 forwarding configured | [`s3-forwarding-configured.sql`](https://github.com/asymptote-labs/agent-beacon/blob/main/packaging/macos/fleet/policies/s3-forwarding-configured.sql) |
+ | Beacon: inventory heartbeat within 4 days | [`inventory-heartbeat-recent.sql`](https://github.com/asymptote-labs/agent-beacon/blob/main/packaging/macos/fleet/policies/inventory-heartbeat-recent.sql) |
+ </Tab>
+</Tabs>
+
+## 4. Install Beacon on a pilot Mac
+
+In Fleet, go to **Hosts** and open one of the pilot Macs. On its **Software** tab, open **Library**, find **Beacon Endpoint Agent**, and click **Install**. The **Status** column changes to **Installed** when it's done; click the status to see the installer output.
+
+What happens on the Mac:
+
+- Fleet runs `installer -pkg <package> -target /`.
+- The package installs Beacon under `/opt/beacon` and starts the collector.
+- It configures Claude Code and Codex for the user logged in at the Mac.
+- There are no prompts, no sign-in, and nothing is sent off the Mac yet.
+
+**Check it worked.** The **Beacon: installed** and **Beacon: collector running** policies pass the next time Fleet checks the host's policies. Click **Refetch** on the host page to check now.
+
+To check on the Mac itself:
```bash
-BEACON_S3_BUCKET="example-security-logs" \
-AWS_REGION="us-west-2" \
-BEACON_S3_PREFIX="beacon-prod" \
-./configure-beacon-macos-s3.sh --yes --dry-run --skip-software
+sudo /opt/beacon/bin/beacon endpoint status --system
```
-Then run it against your Fleet server:
-
-```bash
-./configure-beacon-macos-s3.sh
```
-
-It asks for:
-
-| Prompt | Example |
-| --- | --- |
-| Fleet URL | `https://fleet.example.com` |
-| Fleet API token | from Fleet Settings |
-| Team ID | a number; the helper lists teams |
-| Automatic install | `n` for a pilot |
-| S3 bucket | `example-security-logs` |
-| AWS region | `us-west-2` |
-| S3 prefix | `beacon-prod` |
-| AWS access key and secret | the writer key |
-
-Non-interactive:
-
-```bash
-FLEET_URL="https://fleet.example.com" \
-FLEET_TOKEN="..." \
-FLEET_TEAM_ID="1" \
-BEACON_S3_BUCKET="example-security-logs" \
-AWS_REGION="us-west-2" \
-BEACON_S3_PREFIX="beacon-prod" \
-AWS_ACCESS_KEY_ID="..." \
-AWS_SECRET_ACCESS_KEY="..." \
-./configure-beacon-macos-s3.sh --yes
+Beacon Endpoint Agent <version>
+Config: /Library/Application Support/Beacon/Endpoint/config.json
+Runtime log: /var/log/beacon-agent/runtime.jsonl
+Collector: grpc=true http=true
+Service: loaded=true running=true
+Harness: Claude Code <version> telemetry=enabled
+Harness: Codex CLI <version> telemetry=enabled
+Last event: present
```
-`--check-only` enables Beacon update monitoring without installing packages.
-
-If you use Fleet GitOps, the next GitOps apply can overwrite these API changes. Fold the package, scripts, and `$FLEET_SECRET_*` variables into the GitOps repo, or rerun the helper after apply.
-
-## What the helper does
-
-On your workstation it:
-
-1. Downloads the latest Apple Silicon `.pkg` from GitHub Releases and checks the SHA-256.
-2. Uploads that package as Fleet software on the team you chose. The install script is Fleet's default `installer -pkg "$INSTALLER_PATH" -target /`. The Beacon package postinstall then configures the system collector. The uninstall script calls Beacon's cleanup helper, because Fleet's default `.pkg` uninstall only removes `.app` bundles.
-3. Stores the AWS keys as Fleet secret variables so they are hidden in the Fleet UI.
-4. Creates three host scripts:
- - `beacon-enable-self-updates.sh`
- - `beacon-configure-s3-forwarding.sh`
- - `beacon-validate.sh`
-5. Creates saved queries for install state, collector health, and S3 forwarder health.
-
-The S3 host script calls the helper that ships in the package, `/opt/beacon/jamf/claude/s3/install-forwarder.sh`. The path says `jamf` because that is where the package puts it. Fleet uses the same file.
-
-Fleet replaces `$FLEET_SECRET_*` when it sends a script to a host. The script never prints those values. Fleet still records script output, so do not `echo` keys.
-
-## 3. Install Beacon on a pilot Mac
-
-In Fleet:
-
-1. Open **Software**, select the team, and open the Beacon package.
-2. Target a small label of Apple Silicon Macs. Do not target every host yet.
-3. Install from the host's **Software** tab, or wait if you turned on automatic install.
-
-The package install is enough for collection. Self-updates and S3 are still off at this point.
+`running=true` and `telemetry=enabled` are the lines that matter. A line reading `Beacon Managed: not connected` is expected: Beacon's hosted service isn't used in this setup.
-## 4. Enable self-updates and S3
+<Note>
+ The package configures the agents of whoever is logged in at the Mac when it installs. If nobody was logged in, for example during Setup Assistant, run this after someone logs in, either as a Fleet script or on the Mac:
+ `sudo /opt/beacon/bin/beacon endpoint user-config repair-installed --system`
+</Note>
-After the package is installed, run the two scripts on those hosts, in this order:
+## 5. Turn on S3 forwarding
-1. `beacon-enable-self-updates.sh`
-2. `beacon-configure-s3-forwarding.sh`
+On the same host page in Fleet, open **Actions > Run script** and run `beacon-configure-s3-forwarding.sh`. Open the result in the host's **Activity** list. Its output should end with `S3 Vector forwarder configured.` and a `state = running` line.
-Then run `beacon-validate.sh` if you want a quick status dump.
+To keep Beacon up to date automatically, also run `beacon-enable-self-updates.sh`. See [Updates](#updates).
-On one Mac:
+**Confirm delivery.** On the Mac, write a test event:
```bash
-sudo /opt/beacon/bin/beacon endpoint status --json
-sudo /opt/beacon/bin/beacon endpoint update status
-sudo launchctl print system/com.beacon.endpoint.collector
-sudo launchctl print system/com.beacon.endpoint.updater
-sudo launchctl print system/com.beacon.endpoint.s3-forwarder
+sudo /opt/beacon/bin/beacon endpoint s3 validate --system
```
-Collector, updater, and S3 forwarder should be loaded. The updater LaunchDaemon is idle most of the day and only runs in its scheduled windows.
-
-## 5. Confirm S3 delivery
-
-Write a test runtime event:
-
-```bash
-sudo /opt/beacon/bin/beacon endpoint test-event \
- --system \
- --log-path /var/log/beacon-agent/runtime.jsonl
-```
-
-Write an inventory heartbeat:
-
-```bash
-sudo /opt/beacon/bin/beacon endpoint inventory heartbeat \
- --system \
- --force \
- --trigger manual \
- --working-dir /Users/Shared \
- --log-path /var/log/beacon-agent/runtime.jsonl
-```
-
-Vector batches uploads. The packaged config waits up to five minutes (`timeout_secs = 300`) before the first object appears.
+The forwarder uploads in batches, so allow up to five minutes. Then, from a machine with AWS access, list the uploaded objects and look for the test event:
```bash
-aws s3 ls "s3://${BEACON_S3_BUCKET}/${BEACON_S3_PREFIX}/runtime/" \
- --recursive \
- --region "$AWS_REGION"
-
-aws s3 ls "s3://${BEACON_S3_BUCKET}/${BEACON_S3_PREFIX}/inventory/" \
- --recursive \
- --region "$AWS_REGION"
+aws s3 ls "s3://example-security-logs/beacon-prod/runtime/" --recursive
+aws s3 cp "s3://example-security-logs/beacon-prod/runtime/date=<YYYY-MM-DD>/<object>.jsonl.gz" - \
+ | gzip -dc | grep "Beacon endpoint S3 validation event"
```
-Inspect an object:
+In Fleet, **Beacon: S3 forwarder running** and **Beacon: S3 forwarding configured** now pass for this Mac.
-```bash
-aws s3 cp "s3://${BEACON_S3_BUCKET}/${BEACON_S3_PREFIX}/runtime/date=<YYYY-MM-DD>/<object>.jsonl.gz" - \
- --region "$AWS_REGION" | gzip -dc | head
-```
+## 6. Roll out to the rest of your Macs
-## Set this up in the Fleet UI instead
+When the pilot looks right:
-Skip the helper if you want to click through Fleet yourself.
+1. **Put the Macs in scope.** Add them to the team, or repeat steps 3 to 5 for another team.
+2. **Install Beacon automatically.** With the helper, rerun it with `FLEET_AUTOMATIC_INSTALL=true`. In the Fleet UI, go to **Policies**, click the **Automations** cell of the **Beacon: installed** policy, check **Install software**, select **Beacon Endpoint Agent**, and click **Save**. Fleet then installs Beacon on every Apple Silicon Mac in the team where that policy fails.
+3. **Turn on S3 for each new Mac.** In the same way, give **Beacon: S3 forwarding configured** a **Run script** automation with `beacon-configure-s3-forwarding.sh`. Fleet then runs the script on each Mac where forwarding isn't set up yet. To turn on self-updates everywhere, run `beacon-enable-self-updates.sh` on the team's hosts: select them on the **Hosts** page and click **Run script**.
+4. **Watch the policies.** Each **Beacon:** policy passes only when that part of Beacon is healthy on the host. A failing host tells you which part to look at.
-### Upload the package
+<Warning>
+ Leave the package's own **Deploy** switch (called **Automatic install** before Fleet 4.83) off. For a `.pkg`, the policy it creates looks for an app bundle to decide whether the package is installed, and Beacon has none. That policy never passes, so Fleet keeps reinstalling. Use the **Beacon: installed** policy instead.
+</Warning>
-1. Download `BeaconEndpointAgent-<version>-arm64.pkg` from the [latest GitHub release](https://github.com/asymptote-labs/agent-beacon/releases/latest).
-2. In Fleet, open **Software**, select the team, and add a custom package.
-3. Leave the default install script. Do not add a post-install script.
-4. Replace the uninstall script with:
+## Running Beacon
-```bash
-#!/bin/sh
-set -eu
-if [ -x /opt/beacon/jamf/scripts/full-cleanup.sh ]; then
- /opt/beacon/jamf/scripts/full-cleanup.sh
-elif [ -x /opt/beacon/fleet/scripts/uninstall.sh ]; then
- /opt/beacon/fleet/scripts/uninstall.sh
- rm -rf /opt/beacon "/Library/Application Support/Beacon" \
- /Library/LaunchDaemons/com.beacon.endpoint.*.plist
- pkgutil --forget ai.asymptote.beacon.endpoint >/dev/null 2>&1 || true
-fi
-```
+### What reaches your bucket
-See [Deploy software](https://fleetdm.com/guides/deploy-software-packages) for targeting and automatic install.
+- **Every line of both logs,** as gzipped JSON lines.
+- **Full agent activity,** after local redaction of secrets and a 64 KB limit per event. That includes prompts, the commands agents ran and their output, tool inputs and outputs, and file paths and diffs. This path has no metadata-only option.
+- **The host name.** Object keys don't include the host. Each record has the Mac's name in `endpoint.hostname`.
+- **The date in the key** is the UTC date the forwarder handled the event, not when the event happened. Use each record's `timestamp` for the event time.
+- **What's included from before step 5.** Runtime events are uploaded from the moment the forwarder first starts, so earlier history isn't included. Inventory is uploaded from the beginning. To include a Mac's earlier runtime history, change `end` to `beginning` on the script's `BEACON_VECTOR_READ_FROM` line before the script first runs on that Mac. Later runs continue from where the forwarder left off.
+- **How often.** Each Mac uploads a batch per log every five minutes, or sooner when a batch reaches 10 MB.
-### Add secret variables
+### Updates
-In **Controls > Variables**, add:
+Self-updates stay off until you run `beacon-enable-self-updates.sh`. After that, each Mac checks for a new release a few times during local business hours. It verifies the package's checksum and Apple notarization, installs it, and rolls back if the new version fails its health check. S3 forwarding keeps running across updates.
-| Variable name | Used in scripts as |
-| --- | --- |
-| `BEACON_AWS_ACCESS_KEY_ID` | `$FLEET_SECRET_BEACON_AWS_ACCESS_KEY_ID` |
-| `BEACON_AWS_SECRET_ACCESS_KEY` | `$FLEET_SECRET_BEACON_AWS_SECRET_ACCESS_KEY` |
-| `BEACON_AWS_SESSION_TOKEN` | `$FLEET_SECRET_BEACON_AWS_SESSION_TOKEN` (only if you use temporary keys) |
+- To only record that an update is available, use `update enable --check-only` in the script.
+- To update through Fleet instead, rerun the helper after a new release. It uploads the new package to the same software title.
+- To point Macs at a release manifest you host, write it to `/Library/Application Support/Beacon/Endpoint/managed.json`:
-### Add the host scripts
+ ```json
+ { "manifest_url": "https://updates.example.com/beacon/update-manifest.json" }
+ ```
-**Enable self-updates:**
+If an update can't restart the S3 forwarder afterwards, the install fails with `could not restore existing forwarder com.beacon.endpoint.s3-forwarder`. It fails on purpose, so forwarding never stops without anyone noticing.
-```bash
-#!/bin/sh
-set -eu
-BEACON="${BEACON_BIN:-/opt/beacon/bin/beacon}"
-if [ ! -x "$BEACON" ]; then
- echo "Beacon is not installed at $BEACON" >&2
- exit 1
-fi
-"$BEACON" endpoint update enable
-"$BEACON" endpoint update status
-```
+### Capture more agents
-**Configure S3.** Change the bucket, region, and prefix, then save this as `beacon-configure-s3-forwarding.sh`:
+The package sets up Claude Code and Codex. To add others, run a Fleet script like this on the Macs:
```bash
#!/bin/sh
-set -eu
-INSTALLER="${BEACON_S3_VECTOR_SCRIPT:-/opt/beacon/jamf/claude/s3/install-forwarder.sh}"
-VECTOR="${BEACON_VECTOR_BIN:-/opt/beacon/bin/vector}"
-if [ ! -x "$INSTALLER" ]; then
- echo "S3 forwarder helper missing at $INSTALLER; install the Beacon package first" >&2
- exit 1
-fi
-if [ ! -x "$VECTOR" ]; then
- echo "Vector missing at $VECTOR" >&2
- exit 1
-fi
-export BEACON_S3_BUCKET="example-security-logs"
-export AWS_REGION="us-west-2"
-export BEACON_S3_PREFIX="beacon-prod"
-export BEACON_S3_STORAGE_CLASS="STANDARD"
-export BEACON_VECTOR_READ_FROM="${BEACON_VECTOR_READ_FROM:-end}"
-export AWS_ACCESS_KEY_ID="$FLEET_SECRET_BEACON_AWS_ACCESS_KEY_ID"
-export AWS_SECRET_ACCESS_KEY="$FLEET_SECRET_BEACON_AWS_SECRET_ACCESS_KEY"
-"$INSTALLER"
-echo "S3 Vector forwarder configured. Credential values were not printed."
+/opt/beacon/bin/beacon endpoint user-config repair-installed --system --harness cursor,gemini
```
-Install the package first, then run those two scripts on the host.
-
-## Policies to add
-
-After the first Mac is installed, the package also drops queries under `/opt/beacon/fleet/queries`. Useful checks:
-
-| Query | Healthy value |
-| --- | --- |
-| `beacon-version.sql` | `installed` |
-| `collector-service-health.sql` | `running` |
-| `s3-vector-forwarder-health.sql` | `running` |
-| `s3-vector-forwarding-configured.sql` | `configured` |
-| `last-event-age-seconds.sql` | less than `86400` |
-
-## Troubleshooting
+Agents that are already set up stay set up, so list only the ones you're adding. The names this command accepts are `claude`, `codex`, `gemini`, `cursor`, `vscode` (hooks only), `opencode`, `cline`, `factory`, `openhands`, `kiro`, `kimi`, `dsh`, `pi`, `omp`, `prime`, `omo`, `openclaw`, `grok`, `qwen`, `muse`, `hermes`, `devin-cli`, `devin-desktop`, and `antigravity`. Some agents need a step outside Beacon; see [Agent Harness Integrations](/runtimes).
-### The package will not upload
+### Rotate the AWS key
-Custom packages need Fleet Premium and a team ID. Self-hosted Fleet needs installer S3 storage and a load balancer that waits at least five minutes.
+1. Create a second access key for the Beacon IAM user.
+2. Update the Fleet variables. Rerun the helper with the new key, or edit `BEACON_AWS_ACCESS_KEY_ID` and `BEACON_AWS_SECRET_ACCESS_KEY` in **Controls > Variables**.
+3. Run `beacon-configure-s3-forwarding.sh` on every Mac: on the **Hosts** page, select them and click **Run script**. The forwarder remembers where it was, so nothing is uploaded twice.
+4. When every Mac has run it, deactivate and delete the old key. Until then, keep the old key active, because uploads it rejects are lost.
-### Scripts never run
+### Remove Beacon
-Confirm `fleetd` was installed with scripts enabled. In Fleet MDM that is the default. Check **Host details > Activity** for the script result.
+In Fleet, open the host's **Software** tab, then **Library**, and click **Uninstall** on **Beacon Endpoint Agent**. The uninstall script removes:
-### Beacon installed, but S3 is empty
+- Beacon itself;
+- the S3 forwarder;
+- the AWS keys stored on the Mac;
+- the local logs;
+- the package receipt;
+- Beacon's settings from the logged-in user's Claude Code, Codex, and Cursor.
-Confirm the package is on the disk and the S3 script ran after install:
+If the Mac is still in scope of the **Beacon: installed** automation, Fleet installs Beacon again. Move the Mac out of the team first.
-```bash
-ls /opt/beacon/bin/vector
-ls /opt/beacon/jamf/claude/s3/install-forwarder.sh
-sudo launchctl print system/com.beacon.endpoint.s3-forwarder
-sudo tail -n 50 /tmp/com.beacon.endpoint.s3-forwarder.err
-```
+When you remove Beacon everywhere, also delete the IAM access key and the two Fleet variables.
-If `launchctl` says it cannot find the service, rerun `beacon-configure-s3-forwarding.sh`. Wait up to five minutes for Vector to flush.
+## Troubleshooting
-Check that the env file exists without printing secrets:
+<AccordionGroup>
+ <Accordion title="The helper stops with a role or permission error">
+ The helper names the role the refused call needs. Storing AWS keys needs a **global** admin or maintainer, because team roles can't write variables. Use the API-only user from [Create the API token](#create-the-api-token), or add the keys yourself in **Controls > Variables** and run the helper with `BEACON_AWS_CREDENTIAL_MODE=none`.
+
+ On self-hosted Fleet, saving variables also fails with "Please configure a private key" until the Fleet server has `server.private_key` set.
+ </Accordion>
+ <Accordion title="The package won't upload">
+ Custom packages need Fleet Premium and a specific team, not "All teams". On self-hosted Fleet, check that package storage is set up and that load balancer timeouts are at least five minutes.
+ </Accordion>
+ <Accordion title="Scripts never run on the Mac">
+ `fleetd` must have scripts enabled. That's the default with Fleet MDM; otherwise redeploy `fleetd` with `--enable-scripts`. Script results are in the host's **Activity** tab.
+ </Accordion>
+ <Accordion title="Beacon is installed, but no agent activity appears">
+ The package only configures the user who was logged in when it installed. Run this after that user logs in:
+
+ ```bash
+ sudo /opt/beacon/bin/beacon endpoint user-config repair-installed --system
+ sudo /opt/beacon/bin/beacon endpoint doctor --system
+ ```
+
+ `doctor` should report `0 failure(s)`. Agent sessions that were already open keep their old settings, so start a new one.
+ </Accordion>
+ <Accordion title="Nothing arrives in S3">
+ Wait five minutes after the first event. Then check the forwarder on the Mac:
+
+ ```bash
+ sudo launchctl print system/com.beacon.endpoint.s3-forwarder | grep -E 'state =|last exit code'
+ sudo tail -n 50 /tmp/com.beacon.endpoint.s3-forwarder.err
+ ```
+
+ If `launchctl` can't find the service, run `beacon-configure-s3-forwarding.sh` again. To confirm the credentials file exists without printing the keys:
+
+ ```bash
+ sudo sh -c 'sed -E "s/(AWS_ACCESS_KEY_ID|AWS_SECRET_ACCESS_KEY|AWS_SESSION_TOKEN)=.*/\1=<redacted>/" "/Library/Application Support/Beacon/Forwarders/s3-vector.env"'
+ ```
+ </Accordion>
+ <Accordion title="The forwarder log shows a health-check or credentials error at startup">
+ If uploads arrive anyway, the IAM user is missing `s3:ListBucket`, which only the startup check uses. Add it or ignore the error; see [step 2](#2-prepare-s3). If nothing arrives, check the key, the region, and any bucket policy that requires encryption headers.
+ </Accordion>
+ <Accordion title="An update failed with &quot;could not restore existing forwarder&quot;">
+ The new package installed, but the S3 forwarder didn't stay running afterwards. Check `/tmp/com.beacon.endpoint.s3-forwarder.err` on the Mac, fix the cause, and run `beacon-configure-s3-forwarding.sh` again.
+ </Accordion>
+ <Accordion title="Self-updates aren't running">
+ ```bash
+ sudo /opt/beacon/bin/beacon endpoint update status
+ ```
+
+ `Update mode: off` means `beacon-enable-self-updates.sh` hasn't run on this Mac. The Mac also needs to reach GitHub Releases, or the manifest you set in `managed.json`.
+ </Accordion>
+ <Accordion title="Intel Macs">
+ The package is Apple Silicon only. Its pre-install condition makes Fleet skip Intel Macs, and the **Beacon:** policies pass on Intel Macs, so they don't show up as failures.
+ </Accordion>
+</AccordionGroup>
+
+## Reference
+
+### What's on each Mac
+
+| Path | What it is |
+| --- | --- |
+| `/opt/beacon/bin/beacon`, `beacon-otelcol`, `vector` | The CLI, the collector, and the forwarder |
+| `/Library/LaunchDaemons/com.beacon.endpoint.collector.plist` | The collector service |
+| `/Library/LaunchDaemons/com.beacon.endpoint.inventory.plist` | The inventory job, every 6 hours |
+| `/Library/LaunchDaemons/com.beacon.endpoint.s3-forwarder.plist` | The S3 forwarder, after step 5 |
+| `/Library/Application Support/Beacon/Endpoint/` | Beacon's configuration |
+| `/Library/Application Support/Beacon/Forwarders/s3-vector.env` | The AWS keys, readable only by root |
+| `/var/log/beacon-agent/runtime.jsonl` | Agent activity |
+| `/var/log/beacon-agent/inventory_state.jsonl` | Inventory |
-```bash
-sudo sh -c 'sed -E "s/(AWS_ACCESS_KEY_ID|AWS_SECRET_ACCESS_KEY|AWS_SESSION_TOKEN)=.*/\1=<redacted>/" "/Library/Application Support/Beacon/Forwarders/s3-vector.env"'
-```
+### Policies and reports
-### Post-install uninstalled Beacon
+The policies return a row only when that part is healthy, so a failing policy points at a problem. All of them pass on Intel Macs. The files are in [`packaging/macos/fleet/policies`](https://github.com/asymptote-labs/agent-beacon/tree/main/packaging/macos/fleet/policies).
-A failing Fleet post-install script rolls the package back. Remove S3 and self-update from post-install, reinstall the package, and run the two scripts afterward.
+| Policy | Passes when |
+| --- | --- |
+| Beacon: installed | The package receipt and `/opt/beacon/bin/beacon` are present |
+| Beacon: collector running | The collector process is running as root |
+| Beacon: S3 forwarder running | Vector is running with Beacon's S3 config |
+| Beacon: S3 forwarding configured | The credentials file, Vector config, and LaunchDaemon are all present |
+| Beacon: inventory heartbeat within 4 days | Inventory was written in the last 96 hours. Laptops skip scheduled runs while asleep, so a shorter window fails them after a weekend. |
-### Self-update is off
+The reports, in [`packaging/macos/fleet/queries`](https://github.com/asymptote-labs/agent-beacon/tree/main/packaging/macos/fleet/queries), return one row per host with a status value such as `running` or a version number. Don't use them as policies: they return a row on every host, so a policy built from one always passes.
-```bash
-sudo /opt/beacon/bin/beacon endpoint update status
-sudo launchctl print system/com.beacon.endpoint.updater
-```
+### Create the API token
-Re-run `beacon-enable-self-updates.sh`, or:
+The admin helper needs a token for a user with the global admin or maintainer role. An API-only user is the simplest:
-```bash
-sudo /opt/beacon/bin/beacon endpoint update enable
-```
+- **In the Fleet UI:** open the avatar menu, go to **Users**, and choose **Add user > API-only user**. Choose **Global user** and the **Maintainer** role, then click **Add**. The token is shown once, under **API key**.
+- **With fleetctl:** run the command below. It prints the token.
-The Mac needs network access to GitHub Releases, or you must set `BEACON_UPDATE_MANIFEST_URL` to a manifest you host.
+ ```bash
+ fleetctl user create --name "Beacon deploy" --api-only --global-role maintainer
+ ```
-### Intel Macs
+### Admin helper settings
-The current signed endpoint package is Apple Silicon only. Do not scope this software title to Intel hosts.
+| Setting | Meaning |
+| --- | --- |
+| `FLEET_URL`, `FLEET_TOKEN`, `FLEET_TEAM_ID` | Your Fleet server, token, and team |
+| `BEACON_S3_BUCKET`, `AWS_REGION`, `BEACON_S3_PREFIX`, `BEACON_S3_STORAGE_CLASS` | The bucket settings from step 2 |
+| `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY` | The writer key, stored as Fleet secret variables |
+| `BEACON_AWS_CREDENTIAL_MODE=none` | Store no keys. Use this when you add the variables yourself or the Macs get AWS credentials another way. |
+| `FLEET_AUTOMATIC_INSTALL=true` | Install Beacon automatically through the **Beacon: installed** policy |
+| `--dry-run` | Print the plan and scripts without any network calls |
+| `--check-only` | Make the self-update script only check for updates |
+| `--skip-software`, `--skip-scripts`, `--skip-policies`, `--skip-reports` | Leave that part out |
## Related
<Columns cols={2}>
<Card title="Fleet" icon="laptop-file" href="/mdm/fleet">
- Package layout, Fleet scripts, queries, and self-update commands.
+ What the package ships for Fleet, and how to repair or remove it.
</Card>
<Card title="Deploy software in Fleet" icon="box-open" href="https://fleetdm.com/guides/deploy-software-packages">
- Fleet's custom package, script, and targeting model.
+ Fleet's own guide to custom packages, scripts, and targeting.
</Card>
<Card title="Jamf and S3" icon="bucket" href="/guides/jamf-s3-mdm">
- The same Vector S3 path, installed with Jamf Pro instead of Fleet.
+ The same S3 setup, installed with Jamf Pro instead of Fleet.
</Card>
- <Card title="Object storage forwarding" icon="box-archive" href="/guides/macos-object-storage-system">
- S3 and GCS Vector config for a single Mac.
+ <Card title="Telemetry schema" icon="table" href="/telemetry-schema/event-schema">
+ The fields in each record.
</Card>
</Columns>
diff --git a/docs/guides/jamf-anthropic-openai-cursor-mdm.mdx b/docs/guides/jamf-anthropic-openai-cursor-mdm.mdx
index fde41cc1..6c561a5a 100644
--- a/docs/guides/jamf-anthropic-openai-cursor-mdm.mdx
+++ b/docs/guides/jamf-anthropic-openai-cursor-mdm.mdx
@@ -392,9 +392,6 @@ Write an inventory heartbeat:
sudo /opt/beacon/bin/beacon endpoint inventory heartbeat \
--system \
--force \
- --trigger manual \
- --trigger-harness claude \
- --working-dir /Users/Shared \
--log-path /var/log/beacon-agent/runtime.jsonl
```
@@ -550,9 +547,6 @@ Force inventory and inspect the local file:
sudo /opt/beacon/bin/beacon endpoint inventory heartbeat \
--system \
--force \
- --trigger manual \
- --trigger-harness claude \
- --working-dir /Users/Shared \
--log-path /var/log/beacon-agent/runtime.jsonl
tail -n 5 /var/log/beacon-agent/inventory_state.jsonl
diff --git a/docs/guides/jamf-gcs-mdm.mdx b/docs/guides/jamf-gcs-mdm.mdx
index 353427de..73df8b7c 100644
--- a/docs/guides/jamf-gcs-mdm.mdx
+++ b/docs/guides/jamf-gcs-mdm.mdx
@@ -199,9 +199,6 @@ sudo /opt/beacon/bin/beacon endpoint gcs validate --system
sudo /opt/beacon/bin/beacon endpoint inventory heartbeat \
--system \
--force \
- --trigger manual \
- --trigger-harness claude \
- --working-dir /Users/Shared \
--log-path /var/log/beacon-agent/runtime.jsonl
```
diff --git a/docs/guides/jamf-s3-mdm.mdx b/docs/guides/jamf-s3-mdm.mdx
index 441ce1f9..f83e02bd 100644
--- a/docs/guides/jamf-s3-mdm.mdx
+++ b/docs/guides/jamf-s3-mdm.mdx
@@ -290,9 +290,6 @@ Write an inventory heartbeat and snapshot:
sudo /opt/beacon/bin/beacon endpoint inventory heartbeat \
--system \
--force \
- --trigger manual \
- --trigger-harness claude \
- --working-dir /Users/Shared \
--log-path /var/log/beacon-agent/runtime.jsonl
```
@@ -402,9 +399,6 @@ Then force inventory:
sudo /opt/beacon/bin/beacon endpoint inventory heartbeat \
--system \
--force \
- --trigger manual \
- --trigger-harness claude \
- --working-dir /Users/Shared \
--log-path /var/log/beacon-agent/runtime.jsonl
```
@@ -546,9 +540,6 @@ Force inventory and inspect the local file:
sudo /opt/beacon/bin/beacon endpoint inventory heartbeat \
--system \
--force \
- --trigger manual \
- --trigger-harness claude \
- --working-dir /Users/Shared \
--log-path /var/log/beacon-agent/runtime.jsonl
tail -n 5 /var/log/beacon-agent/inventory_state.jsonl
diff --git a/docs/guides/macos-object-storage-system.mdx b/docs/guides/macos-object-storage-system.mdx
index 1e101044..5f7d60be 100644
--- a/docs/guides/macos-object-storage-system.mdx
+++ b/docs/guides/macos-object-storage-system.mdx
@@ -341,9 +341,6 @@ sudo /opt/beacon/bin/beacon endpoint gcs validate --system # when configured
sudo /opt/beacon/bin/beacon endpoint inventory heartbeat \
--system \
--force \
- --trigger manual \
- --trigger-harness manual \
- --working-dir /Users/Shared \
--log-path /var/log/beacon-agent/runtime.jsonl
```
diff --git a/docs/guides/rippling-gcs-mdm.mdx b/docs/guides/rippling-gcs-mdm.mdx
index c9c6484a..3678d4b4 100644
--- a/docs/guides/rippling-gcs-mdm.mdx
+++ b/docs/guides/rippling-gcs-mdm.mdx
@@ -354,9 +354,6 @@ sudo /opt/beacon/bin/beacon endpoint gcs validate --system
sudo /opt/beacon/bin/beacon endpoint inventory heartbeat \
--system \
--force \
- --trigger manual \
- --trigger-harness claude \
- --working-dir /Users/Shared \
--log-path /var/log/beacon-agent/runtime.jsonl
```
diff --git a/docs/mdm/fleet.mdx b/docs/mdm/fleet.mdx
index 721117ef..653848e0 100644
--- a/docs/mdm/fleet.mdx
+++ b/docs/mdm/fleet.mdx
@@ -1,275 +1,159 @@
---
title: "Fleet"
-description: "Deploy and inventory the Beacon endpoint agent with Fleet."
+description: "Deploy the Beacon endpoint agent to Macs with Fleet, and reference for the Fleet scripts, policies, and reports it ships."
---
-## Overview
+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.
-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.
+<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>
-## What Fleet manages
+This page is the reference for what the package gives Fleet admins.
-| Signal | How it helps |
-| --- | --- |
-| Package installation | Deploy Beacon binaries, endpoint scripts, Fleet queries, and Fleet helper scripts. |
-| System endpoint configuration | Install launchd service files and collector configuration for system-mode telemetry. |
-| Runtime telemetry location | Write endpoint events to `/var/log/beacon-agent/runtime.jsonl`. |
-| Inventory and remediation | Use Fleet queries, policies, labels, and scripts to identify missing, stale, or unhealthy installs. |
+## Requirements
-## Package layout
+- **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.
-The macOS package includes Beacon binaries, endpoint helper scripts, and Fleet assets:
+## What the package installs
-```text
-/opt/beacon/bin/beacon
-/opt/beacon/bin/beacon-otelcol
-/opt/beacon/bin/vector
-/opt/beacon/scripts/install-endpoint.sh
-/opt/beacon/scripts/uninstall-endpoint.sh
-/opt/beacon/fleet/queries/*.sql
-/opt/beacon/fleet/scripts/*.sh
-```
-
-The package postinstall performs the default system install. That install creates system configuration and runtime state:
+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/Application Support/Beacon/Endpoint/otelcol.yaml
/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
```
-## 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](/guides/fleet-s3-mdm).
-
-## 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](https://fleetdm.com/guides/deploy-software-packages) for Fleet's package, script, and targeting model.
-
-<Steps>
- <Step title="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.
- </Step>
- <Step title="Scope to a pilot">
- Scope the software to a pilot team or label before broader rollout.
- </Step>
- <Step title="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.
- </Step>
- <Step title="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:
-
- ```bash title="Enable automatic package self-updates"
- /opt/beacon/bin/beacon endpoint update enable
- ```
-
- For visibility without automatic package installation, enable check-only
- mode instead:
+## Policies and reports
- ```bash title="Enable check-only update monitoring"
- /opt/beacon/bin/beacon endpoint update enable --check-only
- ```
+The package ships two kinds of osquery files.
- 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.
- </Step>
- <Step title="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](/guides/fleet-s3-mdm).
- </Step>
- <Step title="Validate the deployment">
- Run the Fleet validation helper on a managed Mac:
+**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.
- ```bash
- /opt/beacon/fleet/scripts/validate.sh
- sudo /opt/beacon/bin/beacon endpoint update status
- ```
- </Step>
-</Steps>
+| 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 |
-## Fleet scripts
+**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.
-Fleet scripts are installed under `/opt/beacon/fleet/scripts`:
+<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>
-| Script | Purpose |
-|--------|---------|
-| `install.sh` | Reinstall or install with optional arguments |
-| `validate.sh` | Check status JSON, Wazuh validation, and LaunchDaemon health |
-| `repair.sh` | Preserve logs and config while repairing collector and harness configuration |
-| `uninstall.sh` | Remove endpoint service files |
+The [admin helper](/guides/fleet-s3-mdm#3-set-up-fleet) creates the five policies and the main reports for you.
-Use the install script when a workflow needs explicit parameters or a reinstall action.
+## Fleet scripts
-Fleet install script positional arguments:
+These are in `/opt/beacon/fleet/scripts` on each Mac:
-```text
-install.sh argument 1: harnesses, default claude,codex; include gemini to opt in Gemini CLI telemetry; do not include GitHub Copilot CLI
-install.sh argument 2: OTLP gRPC port, default 4317
-install.sh argument 3: OTLP HTTP port, default 4318
-install.sh argument 4: collector path, default /opt/beacon/bin/beacon-otelcol
-install.sh argument 5: no-start flag, accepts 1/true/yes
-install.sh argument 6: Splunk HEC endpoint URL
-install.sh argument 7: Splunk HEC token
-install.sh argument 8: optional Splunk index
-install.sh argument 9: optional Splunk source, default beacon-endpoint-agent when configured
-install.sh argument 10: optional Splunk sourcetype, default beacon:endpoint when configured
-install.sh argument 11: Splunk TLS skip-verify flag, accepts 1/true/yes; use only for testing
-install.sh argument 12: optional Splunk HEC CA certificate path
-```
+| 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 repair script positional arguments:
+Fleet runs scripts without arguments, so pass settings as environment variables in a short wrapper script. For example, to add Gemini CLI:
-```text
-repair.sh argument 1: harnesses, default claude,codex; include gemini to opt in Gemini CLI telemetry; do not include GitHub Copilot CLI
-repair.sh argument 2: OTLP gRPC port, default 4317
-repair.sh argument 3: OTLP HTTP port, default 4318
-repair.sh argument 4: Splunk HEC endpoint URL
-repair.sh argument 5: Splunk HEC token
-repair.sh argument 6: optional Splunk index
-repair.sh argument 7: optional Splunk source
-repair.sh argument 8: optional Splunk sourcetype
-repair.sh argument 9: Splunk TLS skip-verify flag
-repair.sh argument 10: optional Splunk HEC CA certificate path
+```bash
+#!/bin/sh
+BEACON_ENDPOINT_HARNESSES=claude,codex,gemini /opt/beacon/fleet/scripts/repair.sh
```
-## 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:
+| 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 |
-- `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`
+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.
-Recommended Fleet policies:
+## Self-updates
-- 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.
+Self-updates are off by default. Turn them on with a Fleet script after the package is installed:
-## 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.
+```bash
+#!/bin/sh
+/opt/beacon/bin/beacon endpoint update enable # or: update enable --check-only
+```
-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.
+`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 is not installed">
- 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:
+ <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
- ls /opt/beacon/fleet/scripts/validate.sh
+ pkgutil --pkg-info ai.asymptote.beacon.endpoint
```
</Accordion>
- <Accordion title="Collector service is not running">
- Check endpoint status and launchd state:
-
+ <Accordion title="Beacon: collector running fails">
```bash
- sudo /opt/beacon/bin/beacon endpoint status --json
- sudo launchctl print system/com.beacon.endpoint.collector
+ sudo /opt/beacon/bin/beacon endpoint status --system
+ sudo /opt/beacon/bin/beacon endpoint doctor --system
```
- If the service file or collector configuration drifted, run `/opt/beacon/fleet/scripts/repair.sh`.
+ `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="Runtime events are stale or missing">
- Verify that the runtime log exists and is writable:
+ <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 test -w /var/log/beacon-agent/runtime.jsonl
- sudo /opt/beacon/bin/beacon endpoint wazuh validate
+ sudo /opt/beacon/bin/beacon endpoint user-config repair-installed --system
```
- 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.
+ Agent sessions that were already open keep their old settings, so start a new one.
</Accordion>
- <Accordion title="Splunk HEC is not configured">
- 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:
-
- ```bash
- sudo /opt/beacon/bin/beacon endpoint status --system --json
- ```
+ <Accordion title="S3 forwarding">
+ See [Troubleshooting in the Fleet and S3 guide](/guides/fleet-s3-mdm#troubleshooting).
</Accordion>
- <Accordion title="Endpoint self-update is not running">
- Check update mode, launchd state, and local system update events:
-
+ <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 launchctl print system/com.beacon.endpoint.updater
sudo tail -n 30 /var/log/beacon-agent/system.jsonl
```
- If the updater is disabled or missing, run the Fleet script or policy command
- that enables the desired mode:
-
- ```bash
- sudo /opt/beacon/bin/beacon endpoint update enable
- ```
-
- To trigger an urgent update check from Fleet, run the scheduled updater path
- immediately:
+ `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>
- <Accordion title="S3 Vector forwarder is not running">
- Confirm the release package includes Vector and that the Fleet S3 script ran after install:
-
- ```bash
- ls /opt/beacon/bin/vector
- ls /opt/beacon/jamf/claude/s3/install-forwarder.sh
- sudo launchctl print system/com.beacon.endpoint.s3-forwarder
- sudo tail -n 50 /tmp/com.beacon.endpoint.s3-forwarder.err
- ```
-
- 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.
- </Accordion>
</AccordionGroup>
## Related
<Columns cols={2}>
<Card title="Beacon with Fleet and S3" icon="bucket" href="/guides/fleet-s3-mdm">
- Upload the package, enable self-updates, and forward runtime plus inventory JSONL to S3.
+ The step-by-step rollout, including S3 forwarding.
</Card>
<Card title="MDM deployment" icon="laptop-mobile" href="/mdm">
- Review the shared macOS MDM deployment model and package layout.
+ The macOS package and how it behaves under any MDM.
</Card>
<Card title="Log forwarding" icon="tower-broadcast" href="/log-forwarding">
- Forward Beacon events into Wazuh, Splunk HEC, Falcon LogScale, Elastic, Datadog, Sumo Logic, Rapid7 InsightIDR, or customer-managed pipelines.
+ Other destinations: Splunk HEC, Falcon LogScale, Elastic, Sentinel, and more.
</Card>
</Columns>
diff --git a/docs/mdm/index.mdx b/docs/mdm/index.mdx
index 887988e7..b45156e6 100644
--- a/docs/mdm/index.mdx
+++ b/docs/mdm/index.mdx
@@ -20,6 +20,7 @@ The macOS package includes Beacon binaries, endpoint scripts, and MDM assets:
/opt/beacon/scripts/uninstall-endpoint.sh
/opt/beacon/jamf/extension-attributes/*.sh
/opt/beacon/jamf/scripts/*.sh
+/opt/beacon/fleet/policies/*.sql
/opt/beacon/fleet/queries/*.sql
/opt/beacon/fleet/scripts/*.sh
```
diff --git a/docs/security/endpoint-operations.mdx b/docs/security/endpoint-operations.mdx
index d40f18d1..0469f16d 100644
--- a/docs/security/endpoint-operations.mdx
+++ b/docs/security/endpoint-operations.mdx
@@ -28,6 +28,7 @@ The macOS package installs Beacon binaries and deployment assets under `/opt/bea
/opt/beacon/scripts/uninstall-endpoint.sh
/opt/beacon/jamf/extension-attributes/*.sh
/opt/beacon/jamf/scripts/*.sh
+/opt/beacon/fleet/policies/*.sql
/opt/beacon/fleet/queries/*.sql
/opt/beacon/fleet/scripts/*.sh
```