> ## 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. # beacon endpoint connect > Connect a Beacon endpoint to Asymptote managed ingest, or disconnect it, and understand what the forwarder stores and sends. ## Command overview `beacon endpoint connect` forwards this endpoint's telemetry to Asymptote so it appears on the Asymptote dashboard. In user mode, the signed-in CLI account authorizes a device-specific ingest key without copying the account token into endpoint state or giving it to Vector. System mode retains browser approval because unattended and 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 live 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 recent work at once. Inventory starts at the beginning of `inventory_state.jsonl` so the dashboard receives the endpoint's current inventory baseline. 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" theme={null} 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 Linux `.deb`/`.rpm`, as `beacon-vector` beside `beacon` from Linux archives and Homebrew on Linux, and as the tap's `beacon-vector` keg from Homebrew on macOS. Intel Macs get 0.50.0, the last x86\_64 macOS build Vector published. `connect` stops 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. Registers this machine's hostname, operating system, architecture, Beacon version, install id, and install mode. User mode uses the signed-in account's `device:enroll` scope; system mode uses browser approval. The server returns a separate `bcn_device_*` ingest key. 5. Writes the device key once to `asymptote/vector-secrets.json` with mode `0600`. The account token is not persisted by the endpoint flow and is never printed. 6. Renders `asymptote/vector.toml` with the selected privacy mode, runs `vector validate` on the file the service will run, stages the session backfill in `cloud-backfill.jsonl` beside the runtime log, 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. Some steps can only fail after the server has issued the key: storing it, validating the config that carries the 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 --json` reports `connect_incomplete: true`. Run `beacon endpoint connect` again once the cause is fixed. ## Session backfill Every connect, first or not and in user or system mode, uploads recent session history so the 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. Before the forwarder starts, Beacon copies the poll events those sweeps wrote, timestamped in the last 30 days and newest kept up to 24 MiB, from the runtime log and its archives into `cloud-backfill.jsonl` beside the runtime log. The forwarder reads that file once from the beginning into the same runtime upload, through the same privacy transform as live events. Hook, OTLP, and plugin events recorded before the connection stay local. A reconnect 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. This can resend events the forwarder already shipped; every event keeps the deterministic event ID it was written with, and the dashboard collapses a resent event on it. `--no-backfill` or `BEACON_BACKFILL=0` connects without uploading history. ## 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, MCP definitions, tool descriptions, retrieval content, evaluation explanations, agent descriptions, request stop sequences, and free-text approval or policy reasons. Stable IDs, hashes, byte counts, actions, timestamps, harness/session/trace identity, `prompt.id`, 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 keep the recorded mode. 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. ## 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 ` | Asymptote dashboard URL. Defaults to `https://asymptotelabs.ai` or `BEACON_DASHBOARD_URL`. Must be `https://` | | `--no-browser` | System mode only: print the approval URL instead of opening a browser | | `--vector-bin ` | Vector binary to run | | `--privacy-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 ` | 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" theme={null} beacon endpoint connect ``` ```bash title="Connect a system-mode install from the signed package" theme={null} sudo /opt/beacon/bin/beacon endpoint connect --system ``` ```bash title="Connect from a machine without a browser" theme={null} sudo beacon endpoint connect --system --no-browser # open the printed URL in a browser where you are signed in ``` ```bash title="Connect with metadata-only forwarding" theme={null} beacon endpoint connect --privacy-mode metadata-only ``` ```bash title="Stop forwarding and remove the local credentials" theme={null} beacon endpoint disconnect ``` ## Checking the connection `beacon endpoint status` prints one line for managed ingest: whether this endpoint is connected, to which organization, the device id, whether the forwarder service is loaded and running, whether the credential is still valid (it asks the ingest service, with a 3-second timeout), and the size of the disk buffer. `--json` exposes the same under `managed_ingest`. ```text theme={null} Asymptote managed ingest: connected to Asymptote Test as device 807c6a11-…; forwarder loaded=true running=true; 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` 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 Wire contract, what leaves the machine, revocation, and offline behavior. The forwarder pack, for running Vector by hand. Inspect the forwarder and credential state. Every file and service Beacon writes. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.