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.
First-run onboarding
The first interactivebeacon endpoint install opens a full-screen terminal wizard:
- Sign in through beacon.sh using the same browser PKCE flow as
beacon login. - Choose Local only or Beacon Cloud. Beacon Cloud sends your agent sessions to your Beacon account and keeps them in the cloud while your account is active. It includes AI-powered search and analytics on Beacon’s hosted dashboard. Unless you opt out, Asymptote uses your sessions for research and AI training and may share de-identified data (beacon.sh/privacy). Local is a dashboard for this machine’s agent activity, kept for as long as the logs are on disk. Your agent activity stays on this machine.
- For Beacon Cloud, choose Standard or Metadata only forwarding.
- Choose the agent tools to set up: Beacon Cloud MCP (Beacon Cloud only) and the Beacon agent skills. 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 happens inside the wizard. 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 to beacon.sh, 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>. - Cancel setup.
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. Beacon Cloud is preselected; choose Local explicitly
to opt out of managed forwarding.
Choosing Beacon Cloud shows a separate disclosure: your agents’ activity on this
machine will be sent to your Beacon account as it happens, and beacon endpoint disconnect stops it. The confirm screen also says that your agent sessions from the
last 30 days, read from their session history on this machine, are uploaded. Live
runtime events recorded before you connect stay local, but the inventory snapshot of
which agent runtimes, skills, and MCP servers are installed does upload once as the
endpoint’s baseline. That detail is documented here rather than shown on the screen
where someone is choosing.
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. Only structural information is sent: which agent and tool
ran, file paths, exit codes, token counts, timestamps, repository and branch names,
and full command lines. Common secret formats in command lines are also masked.
Change the mode later with beacon endpoint connect --privacy-mode. See
beacon endpoint connect for the exact contract.
Confirming Beacon Cloud connects this endpoint in the same command, after the
local install succeeds. The confirm screen names the signed-in account and
states that confirming installs Beacon and starts forwarding to beacon.sh. It
also names Asymptote Labs, Inc. as the operator, the destination, and the
capture mode (Standard or Metadata only). It says how to turn off research and
AI training in Beacon Cloud (profile picture, then Settings), how to change the
capture mode (beacon endpoint connect --privacy-mode), how to stop sending
(beacon endpoint disconnect), and that deleting data is an email to
privacy@asymptotelabs.ai. 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).
Choosing Beacon Cloud uploads that history on the first connection, so the hosted
dashboard shows your recent sessions immediately, and the confirm screen says so.
Choosing Local keeps it on this machine. Other pre-connect runtime history (hook, OTLP
and plugin events) is not uploaded. On the first connection, inventory is read from
the beginning of inventory_state.jsonl so the hosted 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 rather than treating the machine as settled. 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.
Agent tools
After the destination, the wizard offers agent tools. Each is selected by default, so setting them up is opt-out:- Beacon Cloud MCP, offered only when you choose Beacon Cloud, runs
beacon mcp connectfor you: it registers the Beacon Cloud MCP server asbeacon-managedin every detected harness Beacon can configure (Claude Code, Codex CLI, Cursor, VS Code, Gemini CLI, OpenCode and Oh My Pi), so your agents can search the history this machine forwards. It uses OAuth, so Beacon writes only the URL and each harness signs in with beacon.sh the first time it connects. Leaving the row selected is the confirmationbeacon mcp connectwould otherwise ask for. - Beacon agent skills, offered whichever destination you choose, installs the
Beacon Skills for every project: into
~/.agents/skills, and into~/.claude/skillswhen Claude Code is set up. Seebeacon skills. This writes local files only and sends nothing.
beacon mcp connect after beacon endpoint connect. Either failure is a warning that
names the command to retry, never a failed install. A skill directory of the same name
that Beacon did not write is left as it is, and beacon mcp connect leaves any
beacon-managed entry it did not write alone.
Turning a tool off writes nothing for it. The answers are recorded in the onboarding
record as onboarding.cloud_mcp (Beacon Cloud only) and onboarding.agent_skills
(installed or declined). Set up or remove either one later with
beacon mcp connect|disconnect and 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.
The explicit beacon endpoint install --connect flag is unchanged: it presets Beacon Cloud
and skips the destination question.
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.
When setup finishes
When you confirm Beacon Cloud, the install saysInstalling Beacon and connecting to Beacon Cloud... while it works, then ends on a short summary rather than the list of
files it wrote:
End of a Beacon Cloud setup
- 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.
- The hosted dashboard. Sessions from the backfill appear there within a minute; new sessions appear within about 15 seconds of agent activity.
- Where Beacon Cloud MCP was added and what is left to do in each app. A harness that
takes it only by hand is named on a line of its own, and
beacon mcp connect --dry-runprints its steps. If you turned Beacon Cloud MCP off, this line says to runbeacon mcp connectinstead.
--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, beacon endpoint connect, beacon mcp connect, and
installs that skip the wizard keep their full output.
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 the Beacon Cloud answer; explicit
beacon endpoint install --connect remains unaffected.
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 destination: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,
since no account authorized that run. --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.