Command overview
beacon endpoint onboarding inspects the one-time onboarding record written the first
time beacon endpoint install runs in a terminal.
Command syntax
~/.beacon/profile.json. It survives uninstall, so reinstalling
Beacon does not repeat completed setup. The destination question is asked again on the
next interactive install until a destination is recorded; an Asymptote Managed answer is
recorded only once the connect succeeds.
First-run onboarding
The first interactivebeacon endpoint install opens a full-screen terminal wizard:
- Sign in, using the same browser PKCE flow as
beacon login. - Choose Asymptote Managed or Local only.
- For Asymptote Managed, choose Standard or Metadata only forwarding.
- Choose the agent tools to set up. Each is selected; press space to turn one off.
- Review the destination, privacy mode and agent tools, then confirm installation.
beacon endpoint install again when you are ready, or set
BEACON_ONBOARDING=0 to install without the guided setup.
Signing in
The full-screen view stays up while your browser is open, showing the sign-in URL, a spinner, and how long is left before the attempt times out. The URL is printed before any browser is opened, so it is usable even when none can be, and esc during the wait returns to the sign-in screen rather than ending the install. Once a browser has opened, the screen also asks you to open the URL in the browser where you are signed in, and to copy it there if a different browser opened. If sign-in cannot finish — an offline machine, no browser, or the wait expiring — the wizard offers to try again, to show the URL for you to open yourself, or to finish setup without an account and keep telemetry on this machine. Pass--no-browser to
beacon endpoint install to start in that mode.
On Linux, the wizard checks for a display before it starts. With no DISPLAY or
WAYLAND_DISPLAY, or in an SSH session, it goes straight to that screen and says why,
because sign-in finishes by redirecting a browser back to this machine. The choices are
Finish setup without an account (the default, a local install), Show the sign-in
URL (open it on this machine, or on your own computer after forwarding the port it
names; the wizard prints the command, for example
ssh -L 43121:127.0.0.1:43121 <this machine>), and Cancel setup. An SSH session
with X11 forwarding (ssh -X) counts as having a display.
Signing in establishes account identity only. It does not register a managed endpoint,
start Vector, or send telemetry.
Asymptote Managed
Choosing Asymptote Managed shows a separate disclosure: your agents’ activity on this machine will be sent as it happens, andbeacon endpoint disconnect stops it.
Standard sends prompts, responses, tool activity, command output, file diffs, and file
contents returned by tools. Common secret formats, such as API keys and tokens, are
masked on your machine before anything is sent. Masking is pattern-based and may not
catch everything, and the upload may include source code, file contents, and
confidential information. Metadata only removes prompts, responses, reasoning, tool arguments
and results, command output, file diffs, and file contents on your machine before
anything is sent; which agent and tool ran, file paths, exit codes, token counts,
timestamps, repository and branch names, and full command lines (with common secret
formats masked) are still sent. Change the mode later with
beacon endpoint connect --privacy-mode. See
beacon endpoint connect for the exact contract.
Confirming connects this endpoint in the same command, after the local install
succeeds. The confirm screen names the signed-in account, the destination, and the
privacy mode, and states that confirming installs Beacon and starts forwarding; that
screen is where forwarding is authorized. An endpoint that is already enrolled is not
re-enrolled: enrollment rotates the device key, so a connected machine keeps the key it
has and simply records the destination.
The install reads the last 30 days of agent sessions from each runtime’s own session
store into the local log (the session backfill).
Asymptote Managed uploads that history on the first connection, and the confirm screen
says so; Local keeps it on this machine. Other pre-connect runtime history (hook, OTLP
and plugin events) is not uploaded. Inventory is read from the beginning of
inventory_state.jsonl so the dashboard receives the endpoint’s current inventory
baseline.
The managed destination is recorded only once enrollment succeeds. If it fails, the
local install still succeeds, says that the machine is not connected yet, and prints
beacon endpoint connect as the retry command, and the next beacon endpoint install
offers the question again. Verify forwarding with beacon endpoint status --json. The
onboarding record itself is written only after the install succeeds, so a failed
install leaves nothing behind and asks again next time.
When you confirm Asymptote Managed, the install ends on a short summary rather than the
list of files it wrote: the account, device and privacy mode this machine forwards
with; what the session backfill read, with the sync command for any runtime that had
more history than the backfill takes; and the dashboard URL. Beacon then opens the
dashboard in your default browser, except with --no-browser, in an SSH session, or on
Linux without a display; the URL is printed either way. A runtime that needs a restart
or a trust prompt before it collects still says so above the summary, and warnings
still go to stderr. Run beacon endpoint status for the paths and service state
the summary leaves out. Choosing Local, setup on an endpoint that was already
connected, and installs that skip the wizard keep their full output.
Agent tools
After the destination, the wizard offers the Beacon agent skills, selected by default, whichever destination you choose. It installs the Beacon Skills for every project: into~/.agents/skills, and
into ~/.claude/skills when Claude Code is set up. See beacon skills.
This writes local files only and sends nothing.
The skills are installed after the local install succeeds, alongside the runtime hooks.
A failure is a warning that names the command to retry, never a failed install, and a
skill directory of the same name that Beacon did not write is left as it is. Turning
the row off writes nothing. The answer is recorded as onboarding.agent_skills
(installed or declined). Set the skills up or remove them later with
beacon skills install|uninstall. Every later beacon endpoint install and
beacon endpoint repair updates the skill copies Beacon installed to match the new
binary; it never installs skills that were turned off or removed.
When the wizard is skipped
The explicitbeacon endpoint install --connect flag presets Asymptote Managed and
skips the destination question. The destination question is also skipped on an
endpoint already connected to Asymptote.
The wizard never appears non-interactively. Package postinstall scripts, MDM
deployments, --system installs, CI, --dry-run, TERM=dumb, and any piped or
redirected stdin skip it silently, including a redirect to /dev/null. These paths
remain account-free. A machine onboarded before the destination question existed is
asked it once, on its next interactive install.
Flags
Unattended installs
SetBEACON_ONBOARDING=0 to suppress the wizard on an install that would otherwise be
interactive. There is no CLI flag for this: it exists for unattended CI and MDM
workflows. BEACON_MANAGED_INGEST=0 hides only the Asymptote Managed answer from the
destination question; beacon endpoint install --connect still connects when asked explicitly.
Suppress the prompt
BEACON_ONBOARDING_EMAIL and BEACON_ONBOARDING_USAGE variables remain
accepted for existing fleet automation. They use the previous one-time attribution
submission and do not create an account session:
Headless attribution for MDM
BEACON_ONBOARDING_USAGE accepts work, personal, or evaluating. An invalid value
is reported on stderr and ignored rather than failing the install.
Examples
Show what was recorded, including the signed-in email and the answer to the destination question (Telemetry destination: local only … or Asymptote Managed; absent when it has
not been asked, or when an Asymptote answer has not yet been carried through to a
connected machine):
Show the onboarding record
onboarding.destination in ~/.beacon/profile.json;
managed selections also store onboarding.privacy_mode. Setup completed through an
account records onboarding.outcome as authenticated with the signed-in email; setup
finished without one after a failed sign-in records skipped and no email. --json
exposes all of them:
own_infra remains readable for profiles created by older Beacon versions. New
interactive installs choose Local and can configure a customer-managed
forwarding pack afterward.
Clear it so the next install asks again:
Reset the onboarding record
Resend a queued signup
Related
Endpoint install
Configure endpoint telemetry and collector service files.
Endpoint config
Inspect endpoint configuration and validate destination settings.