Skip to main content

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

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

SignalHow it helps
Package installationDeploy Beacon binaries, endpoint scripts, Fleet queries, and Fleet helper scripts.
System endpoint configurationInstall launchd service files and collector configuration for system-mode telemetry.
Runtime telemetry locationWrite endpoint events to /var/log/beacon-agent/runtime.jsonl.
Inventory and remediationUse Fleet queries, policies, labels, and scripts to identify missing, stale, or unhealthy installs.

​
Package layout

The macOS package includes Beacon binaries, endpoint helper scripts, and Fleet assets: 
/opt/beacon/bin/beacon
/opt/beacon/bin/beacon-otelcol
/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: 
/Library/Application Support/Beacon/Endpoint/config.json
/Library/Application Support/Beacon/Endpoint/otelcol.yaml
/Library/LaunchDaemons/com.beacon.endpoint.collector.plist
/var/log/beacon-agent/runtime.jsonl

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

Validate the deployment

Run the Fleet validation helper on a managed Mac:
/opt/beacon/fleet/scripts/validate.sh

​
Fleet scripts

Fleet scripts are installed under /opt/beacon/fleet/scripts:
ScriptPurpose
install.shReinstall or install with optional arguments
validate.shCheck status JSON, Wazuh validation, and LaunchDaemon health
repair.shPreserve logs and config while repairing collector and harness configuration
uninstall.shRemove endpoint service files
Use the install script when a workflow needs explicit parameters or a reinstall action. Fleet install script positional arguments: 
install.sh argument 1: harnesses, default claude,codex
install.sh argument 2: content retention, default full
install.sh argument 3: OTLP gRPC port, default 4317
install.sh argument 4: OTLP HTTP port, default 4318
install.sh argument 5: collector path, default /opt/beacon/bin/beacon-otelcol
install.sh argument 6: no-start flag, accepts 1/true/yes
Fleet repair script positional arguments: 
repair.sh argument 1: harnesses, default claude,codex
repair.sh argument 2: content retention, default full
repair.sh argument 3: OTLP gRPC port, default 4317
repair.sh argument 4: OTLP HTTP port, default 4318

​
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
  • content-retention.sql
  • configured-harnesses.sql
  • runtime-log-writable.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.

​
Repair and uninstall

Use /opt/beacon/fleet/scripts/repair.sh for endpoints where policies report a stale or unhealthy install. 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:
ls /opt/beacon/bin/beacon
ls /opt/beacon/fleet/scripts/validate.sh
Check endpoint status and launchd state:
sudo /opt/beacon/bin/beacon endpoint status --json
sudo launchctl print system/com.beacon.endpoint.collector
If the service file or collector configuration drifted, run /opt/beacon/fleet/scripts/repair.sh.
Verify that the runtime log exists and is writable:
sudo test -w /var/log/beacon-agent/runtime.jsonl
sudo /opt/beacon/bin/beacon endpoint wazuh validate
If validation succeeds but events remain stale, confirm the configured harnesses match the AI runtimes installed on the device and that the local collector ports are not in use by another process.

MDM deployment

Review the shared macOS MDM deployment model and package layout.

SIEM forwarding

Forward Beacon runtime JSONL into Wazuh or customer-managed pipelines.