The cross-harness, self-improving memory layer for AI agents. Join our community: https://discord.com/invite/zdNChS2fBu
Go agent-ai-cliagent-harnessesagent-securitybrowser-extensionciclaude-codecloudcodexcursordetection-engineeringjevknowledge-basememorymobile-device-managementobservabilitysecuritysecurity-information-and-event-managementsecurity-toolstelemetrytraces
---
title: "beacon endpoint connect"
description: "Connect a Beacon endpoint to Beacon Cloud ingest, or disconnect it, and understand what the forwarder stores and sends."
---
## Command overview
`beacon endpoint connect` forwards this endpoint's telemetry to Beacon so it appears on the Beacon dashboard. For a user endpoint, the signed-in CLI account authorizes a device-specific ingest key without another browser approval. The account token is never copied into endpoint state or given to Vector. System mode retains browser approval because unattended/system installs are account-free.
Forwarding is opt-in and revocable. Runtime telemetry starts at the end of the
existing runtime log, so pre-connect runtime events are not sent, with one bounded
exception: every connect uploads the last 30 days of agent sessions read
from the runtimes' own session stores, so the dashboard shows your recent work at once
(see [Session backfill](#session-backfill)). With the
[scheduled session sync](/cli/endpoint-install#scheduled-session-sync) on, its later runs keep adding
session-store records to the log, and those are forwarded as they are written. Inventory starts
at the beginning of `inventory_state.jsonl` so the dashboard receives the endpoint's
current inventory baseline, including inventory records written before connection.
Revoking the device from the dashboard stops ingestion within about a minute.
`beacon endpoint disconnect` stops the forwarder and removes the local credentials.
```bash title="Command syntax"
beacon endpoint connect [flags]
beacon endpoint disconnect [flags]
```
## Prerequisites
- Beacon endpoint installed (`beacon endpoint install`) and writing local JSONL.
- A current `beacon login` session with `device:enroll` scope for user mode.
- Vector 0.50 or newer on the machine. Beacon installs one for you: 0.56.0 at `/opt/beacon/bin/vector` from the macOS package and the Linux `.deb` and `.rpm`, as `beacon-vector` beside `beacon` from the Linux archive and Homebrew on Linux, and as the tap's `beacon-vector` keg from Homebrew on macOS (kept in `libexec`, off your PATH). Intel Macs get 0.50.0, the last x86_64 macOS build Vector published. `connect` stops before opening a browser if no usable Vector is found or if Vector rejects the forwarder config.
- System mode only: a browser where an organization member can approve the device.
## What connect does
1. Locates Vector: `--vector-bin`, then `BEACON_VECTOR_BIN`, then `/opt/beacon/bin/vector`, the `beacon-vector` keg in each Homebrew prefix, a linked `vector` in each Homebrew prefix, then `PATH`. The `beacon-vector` keg is tried ahead of any other Homebrew Vector because it is the copy the tap pins at a supported version.
2. Renders the forwarder config for the selected privacy mode into a scratch directory, with a placeholder key, and runs `vector validate` on it. A config Vector rejects stops `connect` here, before anything is sent to the server.
3. Runs the [session backfill](#session-backfill) sweep into the runtime log, in user and system mode. It is local and runs before a new key is issued.
4. Uses the signed-in account's `device:enroll` scope to register this machine's hostname, operating system, architecture, Beacon version, install id, and install mode. The server returns a separate `bcn_device_*` ingest key. System mode uses the existing browser PKCE device approval instead.
5. Writes the device key once to `asymptote/vector-secrets.json` with mode `0600`. The account token is not persisted by the endpoint flow.
6. Renders `asymptote/vector.toml` with the selected privacy mode and runs `vector validate` on the file the service will run. Stages the session backfill in `cloud-backfill.jsonl` beside the runtime log. Then installs a service unit and starts it.
7. Records the non-secret enrollment, including privacy mode, in `asymptote/enrollment.json` and `config.json`'s `managed_ingest` block.
A first connect that fails at `vector validate` or at loading the service saves no enrollment record, so the endpoint is not connected and `beacon endpoint disconnect` cleans up what was written. After `disconnect --keep-credentials`, status reports not connected and names the kept device id.
Re-running `connect` on a connected machine reuses its install id, so the server rotates the existing device's key in place instead of creating a second device. Because that rotation invalidates the key the running forwarder holds, the new config is validated before enrollment: a re-run whose config Vector rejects leaves the forwarder, its key, and its buffer untouched. Under launchd the new forwarder is loaded only after the old one has exited (Vector drains in-flight requests first), and if the new instance has not started within the wait, `connect` fails and points at `launchctl print` for the job (v1.3.2).
Some steps can only fail after the server has issued the key: storing it, validating the config that carries the server's ingest URL, writing the service unit, starting the service, and recording the enrollment. `connect` writes `asymptote/connect-pending` as soon as the key arrives and removes it only when every step has succeeded. If a step in between fails, `connect` says the connect is incomplete and names the retry, and `beacon endpoint status` reports Beacon Cloud as not connected with `connect_incomplete: true` in `--json`. On a re-connect, the forwarder still running holds the key the server just rotated out, so the previous enrollment record and config are not treated as a working connection. On a first connect, Beacon stops and removes any partial forwarder before returning the error, so a later onboarding retry can safely select local-only telemetry. Run `beacon endpoint connect` again once the cause is fixed. An approval that is cancelled or expires before a key is issued rotates nothing and leaves an existing connection as it was.
## Session backfill
Every connect, first or not and in user or system mode, uploads recent session history so the
Beacon Cloud dashboard is not empty until an agent runs again. Beacon first runs the same bounded
sweep as [`beacon endpoint install`](/cli/endpoint-install#session-backfill): the last 30 days of
sessions from each runtime's own session store, newest first, at most 24 MiB. A system connect reads
the active console user's session stores, as a system install does. `endpoint install --connect`
and the onboarding wizard skip that sweep, because the install has just run it. Then, before the
forwarder starts, Beacon copies the events those sweeps wrote (`harness.collection_method=poll`,
timestamped in the last 30 days, newest kept up to 24 MiB) from the runtime log and its archives
into `cloud-backfill.jsonl` beside the runtime log (`0600`). The forwarder reads that file once from
the beginning into the same runtime upload, through the same privacy transform as live events, so
Metadata-only strips the backfill exactly as it strips live telemetry. Hook, OTLP and plugin events
recorded before the connection stay local.
A re-connect stages the backfill again, so sessions the agents wrote while the endpoint was
disconnected, or before a system endpoint had a console user to read for, still arrive. The runtime
upload resumes from the forwarder's checkpoints, and the forwarder reads each newly staged file as a
new file from the beginning (it fingerprints the file by inode). That can resend events the
forwarder already shipped; every event keeps the deterministic event id it was written with, and
the dashboard collapses a re-sent event on it. A privacy-mode change clears the checkpoints and
replaces the staged file, so the backfill is resent in the new mode. `disconnect` removes the file.
`--no-backfill` or `BEACON_BACKFILL=0` connects without uploading any history.
The backfill is a one-time upload per connect. With the
[scheduled session sync](/cli/endpoint-install#scheduled-session-sync) on, the job keeps reading the
session stores every 15 minutes, and the forwarder ships what it writes as ordinary new runtime
events. When the backfill stopped at its size limit, the job's first runs also read the rest of the
last 30 days, so that history arrives over the next runs rather than not at all.
## Privacy modes
The onboarding wizard records one of two modes. `connect` uses that choice unless
`--privacy-mode` overrides it:
| Mode | Forwarded data |
|------|----------------|
| `standard` | The complete locally sanitized event, including retained prompts, responses, reasoning, tool arguments/results, command output, and diffs. Existing local redaction and size limits still apply. |
| `metadata-only` | Omits prompts, responses, reasoning, tool arguments/results, command output, raw event fields, diffs, inventory file contents, and MCP definitions. It also removes tool descriptions and definitions (`gen_ai.tool.description`, `gen_ai.tool.definitions`), retrieval queries and documents (`gen_ai.retrieval`), evaluation explanations, agent descriptions, request stop sequences, and the free-text reason on approvals and policy decisions (`approval.reason`, `policy.reason`), which can hold an operator's typed feedback; the decision itself remains. Stable ids, hashes, byte counts, actions, timestamps, harness/session/trace identity, the `prompt.id` that groups a turn, token usage, commands, file paths, and other structured metadata remain. |
The transform runs locally in Vector before batching, buffering, or HTTPS upload.
Changing modes requires rerunning `beacon endpoint connect`; install, repair and package
upgrades re-render the config but always keep the recorded mode. The rendered config and
status output record the active choice. A mode change stops the forwarder and clears its
disk buffer before the new config is installed, so events queued under the previous mode
are not uploaded under the new one.
## Keeping the forwarder config current
`connect` is not the only time `vector.toml` is written. `beacon endpoint install`,
`beacon endpoint repair`, and the macOS, `.deb` and `.rpm` package upgrades re-render it in place
for an endpoint that is already connected, so a fix to the forwarder pack, such as a
Metadata-only transform that removes more fields, reaches the endpoint without a re-connect,
which would rotate the device key. The re-render:
- keeps the recorded ingest URL and privacy mode (changing the mode is still a `connect`
decision), and refuses to guess when `enrollment.json` and `config.json` disagree about it;
- never enrolls, makes no network request, and does not read or rewrite the secrets file;
- leaves `vector-data/`, and with it Vector's checkpoints and buffer, as it is;
- validates the new config with the forwarder's own Vector exactly as `connect` does, and only
then replaces the old file atomically. A config Vector rejects is reported as a warning, and the
running forwarder keeps the old one;
- restarts the forwarder when it is running, even when the config is current, after checking that
its Vector still accepts that config. Switching to restricted log access replaces the runtime log
with a copy, and Vector keeps reading the replaced file until it restarts, then resumes in the
copy where it left off; an upgrade may also have installed a new Vector. A stopped forwarder is
never started, and a forwarder whose config was refused, or whose Vector is missing, keeps running
as it was.
The forwarder also reads the first rotated log (`runtime.jsonl.1`), as the Sentinel forwarder
does, so lines written to a replaced log before a restart are picked up at the next rotation
instead of lost. It still ships nothing written before the device was connected.
It does nothing on an endpoint that is not connected, after a connect that did not finish, when
the forwarder service is not installed, or where the service manager cannot run it (supervised
mode); when Vector is missing it warns and keeps the old config. An install run with
`--no-start` leaves the forwarder alone; the macOS package installs that way and then runs
`beacon endpoint asymptote reconcile --system` itself. Run that command by hand (add `--json` for
the result) to reconcile without reinstalling.
## Files and services
| Item | User mode | System mode (macOS) | System mode (Linux) |
|------|-----------|---------------------|---------------------|
| Enrollment record | `~/.beacon/endpoint/asymptote/enrollment.json` (0600) | `/Library/Application Support/Beacon/Endpoint/asymptote/enrollment.json` | `/etc/beacon/endpoint/asymptote/enrollment.json` |
| Install id | `~/.beacon/endpoint/asymptote/install-id` (0600) | `…/Endpoint/asymptote/install-id` | `/etc/beacon/endpoint/asymptote/install-id` |
| Pending-connect marker (only while a connect is unfinished) | `~/.beacon/endpoint/asymptote/connect-pending` (0600, timestamp and reconnect flag only) | `…/Endpoint/asymptote/connect-pending` | `/etc/beacon/endpoint/asymptote/connect-pending` |
| Device key | `~/.beacon/endpoint/asymptote/vector-secrets.json` (0600) | `…/Endpoint/asymptote/vector-secrets.json` | `/etc/beacon/endpoint/asymptote/vector-secrets.json` |
| Vector config | `~/.beacon/endpoint/asymptote/vector.toml` (0644, no secret) | `…/Endpoint/asymptote/vector.toml` | `/etc/beacon/endpoint/asymptote/vector.toml` |
| Staged session backfill | `~/.beacon/endpoint/logs/cloud-backfill.jsonl` (0600) | `cloud-backfill.jsonl` beside the system runtime log (0600) | `cloud-backfill.jsonl` beside the system runtime log (0600) |
| Buffer and checkpoints | `~/.beacon/endpoint/asymptote/vector-data/` | `…/Endpoint/asymptote/vector-data/` | `/etc/beacon/endpoint/asymptote/vector-data/` |
| Service | `~/Library/LaunchAgents/com.beacon.endpoint.asymptote-forwarder.plist` | `/Library/LaunchDaemons/com.beacon.endpoint.asymptote-forwarder.plist` | `/etc/systemd/system/beacon-asymptote-forwarder.service` (user mode: `~/.config/systemd/user/`) |
The directory is `0700`. The device key appears only in the secrets file, which Vector reads through its `file` secret backend; it is in neither `vector.toml`, `config.json`, nor the forwarder's environment. `install-id` pins this machine's install id before enrollment starts, so a connect retried after a failure rotates the same device's key instead of registering a second device.
## Flags
| Flag | Description |
|------|-------------|
| `--dashboard-url <url>` | Beacon service URL. Defaults to `https://beacon.sh` or `BEACON_DASHBOARD_URL`. In user mode it must match the signed-in account service |
| `--no-browser` | System mode only: print the approval URL instead of opening a browser |
| `--vector-bin <path>` | Vector binary to run |
| `--privacy-mode <mode>` | Override the onboarding choice with `standard` or `metadata-only` |
| `--no-backfill` | Do not upload the [session backfill](#session-backfill). `BEACON_BACKFILL=0` does the same |
| `--user` | Use per-user endpoint paths. Enabled by default |
| `--system` | Use system endpoint paths and a LaunchDaemon or system unit. Requires root; the browser opens as the active console user |
| `--log-path <path>` | Runtime JSONL log path |
| `--json` | Print the result as JSON (the device key is never included) |
`disconnect` accepts the same path flags and `--json` (which prints `disconnected`, `kept_credentials`, and `device_id`), plus `--keep-credentials`, which keeps the enrollment record and device key so a later `connect` can reuse this device without a new approval.
## Examples
```bash title="Connect the default per-user install"
beacon endpoint connect --dashboard-url https://beacon.sh
```
```bash title="Connect a system-mode install from the signed package"
sudo /opt/beacon/bin/beacon endpoint connect --system --dashboard-url https://beacon.sh
```
```bash title="Connect a system endpoint from a machine without a browser"
sudo beacon endpoint connect --system --no-browser --dashboard-url https://beacon.sh
# open the printed URL in a browser where you are signed in
```
```bash title="Connect with metadata-only forwarding"
beacon endpoint connect --privacy-mode metadata-only
```
```bash title="Stop forwarding and remove the local credentials"
beacon endpoint disconnect
```
## Checking the connection
`beacon endpoint status` prints one line for managed ingest: whether this endpoint is connected, organization and device identity, active privacy mode, forwarder state, credential validity, and disk-buffer size. `--json` exposes the same under `managed_ingest`. A system install that was never connected, usually an MDM rollout, leaves the line out, as does any install that forwards to its own S3, GCS or Falcon LogScale; status lists those forwarders instead.
```text
Beacon Cloud: connected to Beacon Test as device 807c6a11-…; forwarder loaded=true running=true; privacy Metadata only; credential valid
```
`credential revoked` means the key was revoked or expired, or the approving user is no longer a member of the organization; Vector is logging 401s and dropping batches. Run `beacon endpoint connect --dashboard-url https://beacon.sh` again to re-enroll.
## Revocation and disconnect
Revoke a device, or every device a person approved, from the dashboard's **Beacon Endpoints** page. The ingest service rejects the key within about a minute. `disconnect` is the local half: it stops and removes the forwarder and its config and, unless `--keep-credentials` is given, the enrollment record and device key. `beacon endpoint uninstall` removes the forwarder and the `asymptote/` directory as part of removing the endpoint, except that `--keep-config` keeps the enrollment record and device key. Neither revokes the device server-side; the CLI tells you where to do that.
## Offline behavior
Vector keeps reading into an on-disk buffer (512 MiB for runtime, 256 MiB for inventory) while the network is unavailable and drains it when connectivity returns. The ingest service accepts old timestamps and the dashboard collapses re-sent duplicates on Beacon's deterministic event id, so a laptop that was asleep or offline catches up without loss or double counting, up to the buffer size.
## Related
<Columns cols={2}>
<Card title="Beacon Cloud forwarding" icon="tower-broadcast" href="/log-forwarding/asymptote">
Wire contract, what leaves the machine, revocation, and offline behavior.
</Card>
<Card title="beacon endpoint asymptote" icon="terminal" href="/cli/asymptote">
The forwarder pack, for running Vector by hand.
</Card>
<Card title="Endpoint status" icon="heart-pulse" href="/cli/endpoint-status">
Inspect the forwarder and credential state.
</Card>
<Card title="Endpoint paths" icon="folder-tree" href="/cli/endpoint-paths">
Every file and service Beacon writes.
</Card>
</Columns>