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

# Local

> Install Beacon locally, configure telemetry, and keep the CLI up to date

Install Beacon on macOS, Windows, or Linux, configure the local endpoint telemetry path, and use the repair workflow when you need to reapply configuration after an upgrade. For CI, cloud-agent, and SDK setup paths, see [Agent harness integrations](/runtimes).

## Install Beacon

<Tabs>
  <Tab title="macOS">
    Install Beacon with Homebrew:

    ```bash theme={null}
    brew trust asymptote-labs/tap
    brew tap asymptote-labs/tap
    brew install beacon
    beacon version
    ```

    See the [macOS install guide](/platforms/macos) to configure endpoint telemetry or deploy the signed package to a fleet.
  </Tab>

  <Tab title="Windows">
    Download `BeaconEndpointAgent-<version>-x64.msi` from the [latest release](https://github.com/asymptote-labs/agent-beacon/releases/latest), then run PowerShell as an administrator:

    ```powershell theme={null}
    msiexec /i BeaconEndpointAgent-<version>-x64.msi
    & "$env:ProgramFiles\Beacon\bin\beacon.exe" version
    ```

    See the [Windows install guide](/platforms/windows) for silent installation, checksum verification, and service management.
  </Tab>

  <Tab title="Linux">
    Download the `.deb` or `.rpm` for your architecture from the [latest release](https://github.com/asymptote-labs/agent-beacon/releases/latest):

    <CodeGroup>
      ```bash title="Debian, Ubuntu" theme={null}
      sudo apt install ./beacon_<version>_linux_amd64.deb
      beacon version
      ```

      ```bash title="Fedora, RHEL, Rocky, Alma" theme={null}
      sudo dnf install ./beacon_<version>_linux_amd64.rpm
      beacon version
      ```
    </CodeGroup>

    Replace `amd64` with `arm64` on ARM systems. See the [Linux install guide](/platforms/linux) for rootless and tarball installation.
  </Tab>
</Tabs>

<Accordion title="Example output">
  ```bash title="beacon version output" theme={null}
  $ beacon version
  beacon version 0.0.48
  ```
</Accordion>

## Configure endpoint telemetry

Setting up the endpoint differs by operating system. Start with your platform if you want the
packages, service management, and fleet deployment for it:

<Columns cols={3}>
  <Card title="macOS" icon="apple" href="/platforms/macos">
    Homebrew, or the signed `.pkg` for MDM. launchd.
  </Card>

  <Card title="Windows" icon="windows" href="/platforms/windows">
    `.msi` for x64. Windows service.
  </Card>

  <Card title="Linux" icon="linux" href="/platforms/linux">
    `.deb` and `.rpm` packages. systemd.
  </Card>
</Columns>

The Windows MSI and Linux packages configure a system endpoint during installation. For a Homebrew, tarball, or other CLI-only install, configure a per-user endpoint:

```bash title="Configure endpoint telemetry" theme={null}
beacon endpoint install
beacon endpoint status
```

By default, Beacon configures Claude Code and Codex CLI to export telemetry to a local OpenTelemetry Collector on `127.0.0.1`. Add Gemini when you want Beacon to manage Gemini OTLP settings too:

```bash title="Include Gemini telemetry" theme={null}
beacon endpoint install --harness claude,codex,gemini
```

<Note>
  System-mode install (`--system`) is supported on macOS, Linux distributions that use systemd, and Windows. The default mode uses per-user paths; package installers configure system mode for you.
</Note>

Beacon records supported prompt, tool, command, file, approval, policy, and runtime context when the source runtime emits it. Before events are written to `runtime.jsonl` or sent through configured destinations, Beacon applies redaction, sanitization, truncation, and event-size limits.

Beacon filters generic process/runtime OTLP metrics, Copilot CLI and OpenClaw operational metrics, and high-volume Codex spans out of the local JSONL log by default. Use `--include-runtime-metrics` or `--include-codex-spans` only when troubleshooting.

## Upgrade Beacon

Use the standard Homebrew upgrade flow, then reapply endpoint configuration if needed:

```bash title="Upgrade Beacon" theme={null}
beacon version check
brew trust asymptote-labs/tap
brew update
brew upgrade beacon
beacon endpoint repair
```

`beacon endpoint repair` reapplies managed service files, collector configuration, harness telemetry settings, and forwarding destinations while preserving runtime logs. On v0.0.43 or newer, use `beacon endpoint doctor --fix` when you only need supported health-check drift remediated without a full repair.

## Related

<Columns cols={2}>
  <Card title="Hosting Options" icon="cloud" href="/deployment/hosting-options">
    Choose between Beacon Cloud and the open-source Agent Beacon path.
  </Card>

  <Card title="Endpoint paths and ports" icon="folder-tree" href="/cli/endpoint-paths">
    Review files, logs, collector config, ports, and hook locations.
  </Card>

  <Card title="Endpoint command reference" icon="terminal" href="/cli/endpoint">
    Review install, status, repair, and uninstall commands.
  </Card>

  <Card title="Endpoint repair" icon="wrench" href="/cli/endpoint-repair">
    Reapply service files and telemetry configuration.
  </Card>

  <Card title="Manual CLI installation" icon="file-zipper" href="/cli/manual-install">
    Install from platform archives or build the CLI from source.
  </Card>
</Columns>