Skip to main content

​
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.
Command syntax

​
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 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: 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: 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

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

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

Connect the default per-user install
Connect a system-mode install from the signed package
Connect from a machine without a browser
Connect with metadata-only forwarding
Stop forwarding and remove the local credentials

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

Asymptote Managed forwarding

Wire contract, what leaves the machine, revocation, and offline behavior.

beacon endpoint asymptote

The forwarder pack, for running Vector by hand.

Endpoint status

Inspect the forwarder and credential state.

Endpoint paths

Every file and service Beacon writes.