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

# Quickstart

> Install Beacon, choose where your data lives, and capture your first agent session

## 1. Install Beacon

<Tabs>
  <Tab title="macOS">
    ```bash theme={null}
    brew trust asymptote-labs/tap
    brew install asymptote-labs/tap/beacon
    ```
  </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
    ```

    See the [Windows install guide](/platforms/windows) for more options.
  </Tab>

  <Tab title="Linux">
    Install Beacon using the package for your environment:

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

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

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

Then configure the agents you use:

```bash theme={null}
beacon endpoint install --harness claude,codex,cursor
```

## 2. Choose where your data lives

Beacon supports two modes.

### Local

Keep your agent history on your machine.

Beacon writes telemetry locally and gives you a local dashboard. Nothing is forwarded unless you explicitly configure it.

### Beacon Managed

Send your Beacon telemetry to the hosted service for:

* unlimited retention
* search across past sessions
* cross-harness history
* analytics
* access from anywhere

[Sign up for Beacon Managed](https://beacon.sh/sign-up), then connect your endpoint:

```bash theme={null}
beacon endpoint connect --dashboard-url https://beacon.sh
```

Your browser will open so you can sign in and approve the device.

## 3. Run an agent

Start a new Claude Code, Codex, Cursor, or other supported agent session and use it normally.

Beacon captures the session automatically.

## 4. View your sessions

For the local dashboard:

```bash theme={null}
beacon endpoint dashboard --open
```

If you're using Beacon Managed, your sessions will also appear in the hosted dashboard.

## Check your setup

```bash theme={null}
beacon endpoint status
```

This shows which harnesses are connected, whether the collector is running, and whether Beacon Managed is enabled.

## Useful commands

| Task                      | Command                                                     |
| ------------------------- | ----------------------------------------------------------- |
| Check status              | `beacon endpoint status`                                    |
| Open local dashboard      | `beacon endpoint dashboard --open`                          |
| Connect to Beacon Managed | `beacon endpoint connect --dashboard-url https://beacon.sh` |
| Disconnect from Managed   | `beacon endpoint disconnect`                                |
| Upgrade                   | `brew upgrade beacon`                                       |
| Uninstall                 | `beacon endpoint uninstall --keep-logs`                     |