Skip to main content

Overview

The beacon CLI sends a small number of product usage events to Beacon so we can see whether installs succeed and which setup paths people use. They go to https://beacon.sh/ingest, Beacon’s proxy to PostHog. This is separate from the agent telemetry Beacon records. CLI telemetry never contains session content, prompts, responses, commands, file paths, repository names, hostnames or error messages. Your agent sessions stay where you send them: the local log, your own forwarding destination, or Beacon Cloud if you chose it. The first time you, or a coding agent or script, run a beacon command with telemetry on, the CLI prints this line to stderr, once. It goes to stderr only, so a command’s output stays machine-readable. Runs whose stderr nobody reads never print it, and leave it for a run someone does: scheduled jobs, the beacon processes Beacon starts for itself, MDM and fleet scripts that run beacon as the signed-in user through sudo without a terminal, and beacon mcp serve on stdio, which your coding agent starts:

Turn it off

Set either variable in the environment the CLI runs in:

System mode

CLI telemetry is off by default for --system commands and for any command run as root (sudo, package scripts, MDM, and the system scheduled jobs), so fleet installs make no CLI telemetry requests and write no telemetry state unless an administrator opts in with BEACON_TELEMETRY=1 (true, yes and on work too). DO_NOT_TRACK still turns it off. On Windows, where a process is never root, this covers --system commands. The beacon processes such a run starts as the signed-in user are told telemetry is off too. With telemetry off, the CLI sends nothing and writes no telemetry state. A variable set in the shell you run beacon endpoint install from is also recorded in the user-mode scheduled jobs (inventory and session sync), and the CLI passes it on to the beacon processes it starts as another account, so they stay off too. Development builds (beacon version prints dev) never send telemetry. Events are sent in the background and never slow down or fail a command: on exit the CLI waits at most 1.5 seconds for them, and any network error is ignored. The runtime hooks (beacon-hooks), the collector, shell completion and the git hook entry points never send CLI telemetry.

What every event carries

Identity

Until the CLI knows who you are, events are sent under the machine’s random install ID (install_id in ~/.beacon/profile.json), the same ID the onboarding record uses, and they create no person profile. When you sign in (beacon login or the install wizard), or give beacon endpoint install your email with --email, BEACON_EMAIL, or the install wizard’s optional email question (asked when you finish setup without an account), the CLI links that install ID to you. Your email is sent once as a person property, never as an event property, and the ID it sends events under from then on is the SHA-256 of your lower-cased email. Events from a work email are grouped under its domain; personal mailbox domains such as gmail.com are not. Signing out with beacon logout does not unlink the machine. If you are already signed in when the CLI does not know you yet, for example after signing in with a version that had no telemetry, the next command links the machine to that account the same way, once, whichever way Beacon is installed. It never replaces a person the CLI already knows, beacon login and beacon logout leave it to the new sign-in, and with telemetry off it does not read the sign-in at all. The CLI keeps this state in ~/.beacon/telemetry.json (mode 0600): when the notice was shown, the identified ID, when an install first succeeded, and where the scheduled inventory job stopped reading the runtime log. Deleting the file resets all of them. Updates to it take ~/.beacon/telemetry.lock first, so a command and a scheduled job saving at the same moment never undo each other’s change; an update that cannot get the lock within a second is skipped.

Events

backfill_session_count is the number of sessions the install’s session backfill wrote records for, counted from the runtime log the backfill wrote; it is 0 when the backfill is off. The system packages’ install scripts set BEACON_INSTALL_SOURCE=package, which is how setup_path tells a package install apart. cloud_connect is new when the install connected the endpoint to Beacon Cloud itself, and existing when it is a reinstall or upgrade of an endpoint an earlier run connected, which keeps its device key and reports no history to Beacon Cloud. It is none when destination is local. is_first_for_device on the install events is true only when nothing says Beacon was installed for this account before: no answer from the install wizard, no install manifest (every install writes one), and no earlier successful install recorded in ~/.beacon/telemetry.json, which beacon endpoint uninstall leaves in place. A reinstall, upgrade or repair, including one an agent or script runs, is false. To send each session once, the CLI keeps truncated SHA-256 hashes of the sessions it has reported in ~/.beacon/telemetry-sessions.json (mode 0600, at most 5,000), and updates it under a lock file beside it, telemetry-sessions.lock, so two runs that finish together do not report the same session twice. A run that cannot get the lock within a second sends nothing, and a later run reports those sessions. It never stores or sends session IDs. The scheduled inventory job also keeps how far into the runtime log it has read in ~/.beacon/telemetry.json, with a hash of the log file’s first line and when it read it. Its first run only records where the log ends, so earlier sessions are never reported as live, and so does a run more than three days after the last one (telemetry was off, or the machine was). When the log has rotated since the last run, the job finds the file it was reading among the archives by that hash and reads on from where it stopped, then the newer archives and the live log. Only records a collector wrote count; the records Beacon writes about a session itself, such as a share or a commit link, do not. A system scheduled sync that runs without a home directory sends nothing.