Jamf

Deploy and inventory the Beacon endpoint agent with Jamf Pro.

Jamf

Jamf Pro can deploy and inventory the local Beacon endpoint agent on managed Macs. Beacon’s Jamf support is deployment-native: Jamf installs the package and reports endpoint health while Beacon writes telemetry to local JSONL without requiring a hosted account or Jamf Pro API credentials.

What Jamf manages

Signal	How it helps
Package installation	Deploy Beacon binaries, endpoint scripts, Jamf helpers, and extension attributes.
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 extension attributes and Smart Groups to identify missing, stale, or unhealthy installs.

Package layout

The macOS package includes Beacon binaries, endpoint helper scripts, and Jamf assets:

/opt/beacon/bin/beacon
/opt/beacon/bin/beacon-otelcol
/opt/beacon/scripts/install-endpoint.sh
/opt/beacon/scripts/uninstall-endpoint.sh
/opt/beacon/jamf/extension-attributes/*.sh
/opt/beacon/jamf/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 Jamf Pro

Build or obtain a signed and notarized Beacon macOS package, upload it to Jamf Pro, and attach the package to a policy scoped to a pilot Smart Group. The package postinstall performs the default system install, so no script is required for the common deployment path.

1. Upload the Beacon package

   Upload the signed Beacon macOS package to Jamf Pro. The package installs Beacon binaries under /opt/beacon and includes Jamf helper scripts and extension attributes.

2. Create an install policy

   Create a Jamf policy that installs the Beacon package. Add the install helper only when the policy needs explicit parameters or a reinstall action:

   /opt/beacon/jamf/scripts/install.sh "$@"
   
3. Configure optional policy parameters

   Set Jamf script parameters when using the install helper to override the defaults:

   Parameter	Value
   4	Harnesses, default claude,codex.
   5	Content retention, default full.
   6	OTLP gRPC port, default 4317.
   7	OTLP HTTP port, default 4318.
   8	Collector path, default /opt/beacon/bin/beacon-otelcol.
   9	No-start flag for install.sh only, accepts 1, true, or yes.
   10	Splunk HEC endpoint URL.
   11	Splunk HEC token.
   12	Optional Splunk index.
   13	Optional Splunk source, default beacon-endpoint-agent when configured.
   14	Optional Splunk sourcetype, default beacon:endpoint when configured.
   15	Splunk TLS skip-verify flag, accepts 1, true, or yes; use only for testing.
   16	Optional Splunk HEC CA certificate path.

4. Validate the deployment

   After the package deploys, validate the endpoint state on a managed Mac:

   sudo /opt/beacon/bin/beacon endpoint status --json
   sudo /opt/beacon/bin/beacon endpoint wazuh validate
   sudo launchctl print system/com.beacon.endpoint.collector
   

Build a test package

When building from source, build the CLI and collector first, then assemble the macOS package:

cd cli/beacon
make build
cd ../..

cd collector-builder
ocb --config builder.yaml
cd ..

sh packaging/macos/build-pkg.sh

Set PKG_SIGN_IDENTITY to sign with pkgbuild, and set NOTARYTOOL_PROFILE to submit and staple the package with Apple’s notary service.

Inventory with extension attributes

Upload the scripts from /opt/beacon/jamf/extension-attributes to Jamf Pro to inventory:

• Beacon version
• Collector service health
• Last runtime event age in seconds
• Content retention mode
• Configured harnesses
• Runtime log writability
• Splunk HEC forwarding configuration state

Suggested Smart Groups:

• Beacon version is not_installed.
• Collector service health is not running.
• Last runtime event age is greater than 86400.
• Content retention is not full.
• Runtime log writability is not writable or creatable.
• Splunk HEC forwarding is not_configured when HEC export is required.

Use /opt/beacon/jamf/scripts/install-cursor-hooks.sh as a separate user-context policy for Cursor telemetry. Cursor hook configuration is per user and should run only when an interactive console user is present.

Troubleshooting

Beacon is not installed

If the Beacon version extension attribute reports not_installed, confirm the Jamf policy installed the Beacon package.

On the device, verify that the expected files exist:

ls /opt/beacon/bin/beacon
ls /opt/beacon/jamf/scripts/install.sh

Re-run the install policy after confirming the package is scoped to the device.

Collector service is not running

Check the endpoint status and launchd service 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/jamf/scripts/repair.sh from a Jamf remediation policy.

Runtime events are stale or missing

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. If Cursor hook events are missing, confirm the separate user-context Cursor hook policy has run for the logged-in user.

Configured harnesses are wrong

Check Jamf parameter 4 on the install policy. The default is claude,codex; set the parameter explicitly when you want a narrower or broader harness list.

After changing the policy, run the repair script so Beacon reapplies harness telemetry configuration without removing runtime logs.

Content retention is unexpected

Check Jamf parameter 5 on the install policy. The default is full, with redacted and metadata available when approved for your deployment.

Use the content retention extension attribute to verify the deployed mode across managed Macs.

Splunk HEC is not configured

Check Jamf parameters 10 and 11, or the BEACON_SPLUNK_HEC_ENDPOINT and BEACON_SPLUNK_HEC_TOKEN environment variables used by the install policy.

Use the Splunk HEC forwarding extension attribute to verify whether endpoint configuration contains a Splunk destination. On the device, confirm the non-secret destination fields:

sudo /opt/beacon/bin/beacon endpoint status --system --json

Repair and uninstall

Use /opt/beacon/jamf/scripts/repair.sh as a remediation policy for Macs where extension attributes report a stale or unhealthy install.

Use /opt/beacon/jamf/scripts/uninstall.sh to remove endpoint service files. Set BEACON_KEEP_LOGS=1 or Jamf parameter 4 to preserve runtime logs during removal. Set BEACON_KEEP_CONFIG=1 or Jamf parameter 5 to preserve harness telemetry configuration.

Related

MDM deployment

Review the broader Jamf, Fleet, and macOS MDM deployment model.

Fleet

Deploy Beacon with Fleet software, policies, queries, and scripts.

SIEM forwarding

Forward Beacon events into Wazuh, Splunk HEC, or customer-managed pipelines.

Smoke test

Before publishing or distributing a package, run the non-root endpoint smoke test on a macOS host or VM:

sh packaging/macos/smoke-endpoint.sh

The smoke test builds a temporary Beacon binary, uses a temporary HOME, runs a default user-mode install with --no-start, validates status and Wazuh output, installs Cursor hooks, uninstalls, and preserves the runtime log long enough to assert expected events were written.