Skip to main content

​
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). With the 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.
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 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 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: 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 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: 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 only when the content changed and the forwarder is running (a stopped one reads the new config when it next starts).
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

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 a system endpoint 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, 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.
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.

Beacon Cloud 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.