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

# Try Beacon on One Mac

> Install the signed macOS package on a single Mac and see what Beacon captures before rolling it out with MDM

Install the package your MDM would deploy on one Mac and look at what Beacon records. This install needs no Beacon account and sends nothing off the machine. The package you test here is the same file you later upload to Jamf, Fleet, or Rippling.

You need an Apple Silicon Mac and an administrator account. The package is built for Apple Silicon only. On an Intel Mac, use the [Homebrew install](/platforms/macos#your-own-machine).

## Install

Run this in Terminal while you are logged in at the Mac. It downloads the latest package, checks it against its published SHA-256 and its Apple signature, and installs it.

```bash title="Download, verify, and install" theme={null}
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 /
```

`pkgutil` should print `Status: signed by a developer certificate issued by Apple for distribution` and `Notarization: trusted by the Apple notary service`. If the checksum or signature check fails, nothing is installed.

You can also download `BeaconEndpointAgent-<version>-arm64.pkg` from the [latest release](https://github.com/asymptote-labs/agent-beacon/releases/latest) and open it in Installer. The result is the same.

## What to expect

The package runs a system-mode install as root. There is no setup wizard, no browser window, and no sign-in. Those only appear when someone runs `beacon endpoint install` as a regular user in a terminal.

When the installer finishes, the Mac has:

|             |                                                                                                                                                                                                   |
| ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Binaries    | `/opt/beacon/bin/beacon`, the `beacon-otelcol` collector, and `vector`, which stays idle unless you set up forwarding                                                                             |
| Collector   | LaunchDaemon `com.beacon.endpoint.collector`, running as root and listening on `127.0.0.1:4317` (gRPC) and `127.0.0.1:4318` (HTTP)                                                                |
| Config      | `/Library/Application Support/Beacon/Endpoint/config.json`                                                                                                                                        |
| Runtime log | `/var/log/beacon-agent/runtime.jsonl`                                                                                                                                                             |
| Inventory   | LaunchDaemon `com.beacon.endpoint.inventory`, which runs at load and every 6 hours and writes `/var/log/beacon-agent/inventory_state.jsonl`                                                       |
| Agents      | Claude Code and Codex, configured for the user logged in at the Mac. Beacon adds OpenTelemetry settings and hooks to `~/.claude/settings.json`, `~/.codex/config.toml`, and `~/.codex/hooks.json` |

Nothing leaves the Mac:

* Asymptote Managed is not connected, and no forwarder is running.
* Automatic updates are off.
* The collector listens on loopback only, and hooks never use the network.

The package does not add `beacon` to your `PATH`, so the commands on this page use `/opt/beacon/bin/beacon`.

Claude Code and Codex sessions that were already open keep their old settings. Start a new session to begin capturing.

## Confirm it worked

```bash title="Check the endpoint" theme={null}
sudo /opt/beacon/bin/beacon endpoint status --system
```

```
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
Beacon Managed: not connected (run `beacon endpoint connect`)
Inventory heartbeat: scheduled every 6h0m0s; job loaded=true running=false; last emitted <time>
```

`running=true` and `telemetry=enabled` are the lines that matter. `Beacon Managed: not connected` is expected. Other agents installed on the Mac may also be listed with `telemetry=disabled`, because the package only configures Claude Code and Codex.

For a full check of the service, collector, config, log permissions, and each agent's settings:

```bash title="Diagnose" theme={null}
sudo /opt/beacon/bin/beacon endpoint doctor --system
```

What matters is `0 failure(s)`. Before you run an agent, doctor warns `harness_observed`. That clears after your first session.

<Warning>
  If doctor reports `console_user_configured: fail`, the package could not tell who was logged in
  when it ran, so no agent is sending to the collector. Log in at the Mac and run
  `sudo /opt/beacon/bin/beacon endpoint user-config repair-installed --system`.
</Warning>

## See what it captured

Start a new agent session and give it a task:

```bash theme={null}
claude
```

Then watch events arrive in the runtime log. macOS 15 and later include `jq`. On older versions, drop the `| jq ...` part.

```bash title="Follow the runtime log" theme={null}
tail -f /var/log/beacon-agent/runtime.jsonl | jq -c '{time: .timestamp, harness: .harness.name, action: .event.action}'
```

Or browse sessions and timelines in the local dashboard:

```bash title="Open the dashboard" theme={null}
/opt/beacon/bin/beacon endpoint dashboard --system
```

Then open `http://127.0.0.1:8765`. The dashboard is read-only and listens on loopback only.

Each event records prompts, the commands the agent ran, files it read and wrote, tool calls, approvals, and token usage, depending on what the agent exposes. See the [telemetry schema](/telemetry-schema/event-schema) for the fields.

## Add more agents

The package configures Claude Code and Codex. To capture other agents, name them in the repair command. Agents that are already configured stay configured, so list only the ones you are adding:

```bash title="Add Cursor and Gemini CLI" theme={null}
sudo /opt/beacon/bin/beacon endpoint user-config repair-installed --system --harness cursor,gemini
```

Run it while logged in at the Mac. It configures the agents of whoever is logged in at the console.

The command accepts these names:

| Name            | Agent                                                                              |
| --------------- | ---------------------------------------------------------------------------------- |
| `claude`        | Claude Code                                                                        |
| `codex`         | Codex CLI                                                                          |
| `gemini`        | Gemini CLI                                                                         |
| `cursor`        | Cursor                                                                             |
| `vscode`        | VS Code (hooks only; this command does not write VS Code's OpenTelemetry settings) |
| `opencode`      | OpenCode                                                                           |
| `cline`         | Cline                                                                              |
| `factory`       | Factory Droid                                                                      |
| `openhands`     | OpenHands                                                                          |
| `kiro`          | Kiro                                                                               |
| `kimi`          | Kimi Code                                                                          |
| `dsh`           | DeepSeek Harness                                                                   |
| `pi`            | Pi                                                                                 |
| `omp`           | Oh My Pi                                                                           |
| `prime`         | Prime Agent                                                                        |
| `omo`           | Senpi                                                                              |
| `openclaw`      | OpenClaw Gateway                                                                   |
| `grok`          | Grok Build                                                                         |
| `qwen`          | Qwen Code                                                                          |
| `muse`          | Muse Code                                                                          |
| `hermes`        | Hermes Agent                                                                       |
| `devin-cli`     | Devin CLI                                                                          |
| `devin-desktop` | Devin Desktop                                                                      |
| `antigravity`   | Antigravity CLI                                                                    |

A few agents need a step outside Beacon. GitHub Copilot CLI is set up through its own environment variables, and OpenClaw needs a setting in its own config before Beacon can record token usage. See [Agent Harness Integrations](/runtimes) for the details on each agent.

## Next steps

When the trial looks right, keep the install and pick where the data goes.

<Columns cols={2}>
  <Card title="Roll out with MDM" icon="building-shield" href="/mdm">
    Deploy the same package with Jamf Pro, Fleet, or Rippling.
  </Card>

  <Card title="Connect to Asymptote Managed" icon="cloud-arrow-up" href="/cli/endpoint-connect">
    Run `sudo /opt/beacon/bin/beacon endpoint connect --system` to forward this Mac's events to Asymptote.
  </Card>

  <Card title="Forward to your own tools" icon="share-nodes" href="/log-forwarding">
    Send the runtime log to Splunk, Elastic, Sentinel, S3, and other destinations you run.
  </Card>

  <Card title="Detect threats locally" icon="shield-halved" href="/cli/scan">
    Run the open threat rules over the runtime log with `beacon scan`.
  </Card>
</Columns>

## Remove it

The cleanup helper deletes `/opt/beacon`, which is where it lives, so copy it out first:

```bash title="Remove Beacon completely" theme={null}
sudo install -m 0700 -o root -g wheel \
  /opt/beacon/jamf/scripts/full-cleanup.sh \
  /var/tmp/beacon-full-cleanup.sh
sudo /var/tmp/beacon-full-cleanup.sh
sudo rm -f /var/tmp/beacon-full-cleanup.sh
```

This stops and removes Beacon's LaunchDaemons and deletes `/opt/beacon`, the config under `/Library/Application Support/Beacon`, the logs in `/var/log/beacon-agent`, and the package receipt. It also takes Beacon's entries out of the logged-in user's Claude Code, Codex, and Cursor config. To keep the logs, run the helper as `sudo BEACON_KEEP_LOGS=1 /var/tmp/beacon-full-cleanup.sh`.