Skip to content

The cross-harness, self-improving memory layer for AI agents. Join our community: https://discord.com/invite/zdNChS2fBu

14.2 KB
Raw Blame
---
title: "beacon endpoint onboarding"
description: "Show, reset, or resend the one-time Beacon onboarding record"
---

## Command overview

`beacon endpoint onboarding` inspects the one-time onboarding record written the first
time `beacon endpoint install` runs in a terminal.

```bash title="Command syntax"
beacon endpoint onboarding [flags]
```

The record lives in `~/.beacon/profile.json`. It survives uninstall, so reinstalling
Beacon does not repeat completed setup.

## First-run onboarding

The first interactive `beacon endpoint install` opens a full-screen terminal wizard:

1. Sign in through beacon.sh using the same browser PKCE flow as [`beacon login`](/cli/account-auth).
2. 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](https://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.
3. For Beacon Cloud, choose **Standard** or **Metadata only** forwarding.
4. Choose the agent tools to set up: Beacon Cloud MCP (Beacon Cloud only) and the
   Beacon agent skills. Each is selected; press <kbd>space</kbd> to turn one off.
5. Review the destination, privacy mode and agent tools, then confirm installation.

Move between choices with the arrow keys, continue with <kbd>enter</kbd>, and cancel
with <kbd>esc</kbd>. Cancelling ends the install before anything is written, and the
error says so: run `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 <kbd>esc</kbd> 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**.

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. 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`](/cli/endpoint-connect#privacy-modes) 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
[email protected]. 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](/cli/endpoint-install#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 connect`](/cli/mcp-connect) for you: it registers the Beacon Cloud MCP
  server as `beacon-managed` in 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 confirmation `beacon mcp connect` would otherwise ask for.
- **Beacon agent skills**, offered whichever destination you choose, installs the
  [Beacon Skills](/concepts/beacon-skills) for every project: into `~/.agents/skills`,
  and into `~/.claude/skills` when Claude Code is set up. See [`beacon skills`](/cli/skills).
  This writes local files only and sends nothing.

The skills are installed after the local install succeeds, alongside the runtime hooks.
Beacon Cloud MCP is registered only once the endpoint is connected to Beacon Cloud (or
already was): if enrollment fails, MCP is skipped too and the install says to run
`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 says `Installing Beacon and connecting to
Beacon Cloud...` while it works, then ends on a short summary rather than the list of
files it wrote:

```text title="End of a Beacon Cloud setup"
Beacon is installed and connected to Beacon Cloud as [email protected] (device dev_7f3a, Standard privacy).
Session backfill: 8 events from the last 30 days (Claude Code 6, Codex 2).
  Claude Code: stopped at the backfill size limit; `beacon endpoint claude sync` reads the rest.
Dashboard: https://beacon.sh/dashboard (your recent sessions appear within a minute)
Beacon Cloud MCP added to Claude Code, Cursor, VS Code; sign in to beacon-managed once in each app (Claude Code: /mcp in a new session).
```

In order, the lines give:

1. The account, device and privacy mode this machine forwards with.
2. What the [session backfill](/cli/endpoint-install#session-backfill) read, with the
   sync command for any runtime that had more history than the backfill takes.
3. The hosted dashboard. Sessions from the backfill appear there within a minute;
   new sessions appear within about 15 seconds of agent activity.
4. 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-run` prints its steps. If you turned Beacon Cloud MCP off,
   this line says to run `beacon mcp connect` instead.

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, `beacon endpoint connect`, `beacon mcp connect`, and
installs that skip the wizard keep their full output.

## Flags

| Flag | Description |
|------|-------------|
| `--reset` | Clear the onboarding record so the question is asked again |
| `--resend` | Retry a signup queued by a pre-account onboarding version |
| `--json` | Print the onboarding record as JSON |
| `--user` | Use per-user endpoint paths. Enabled by default |
| `--system` | Use system endpoint paths |

## Unattended installs

Set `BEACON_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.

```bash title="Suppress the prompt"
BEACON_ONBOARDING=0 beacon endpoint install
```

The legacy `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:

```bash title="Headless attribution for MDM"
BEACON_ONBOARDING_EMAIL=[email protected] BEACON_ONBOARDING_USAGE=work \
  beacon endpoint install
```

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

```bash title="Show the onboarding record"
beacon endpoint onboarding
```

The answer is stored as `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:

| Value | Printed as |
|-------|------------|
| `local` | local only (nothing forwarded) |
| `asymptote` | Beacon Cloud |

`own_infra` remains readable for profiles created by older Beacon versions. New
interactive installs choose Local and can configure a customer-managed
[forwarding pack](/log-forwarding) afterward.

Clear it so the next install asks again:

```bash title="Reset the onboarding record"
beacon endpoint onboarding --reset
```

Retry a legacy attribution submission that could not reach Beacon:

```bash title="Resend a queued signup"
beacon endpoint onboarding --resend
```

To have your record deleted, email the install ID shown by this command to
[[email protected]](mailto:[email protected]).

## Related

<Columns cols={2}>
  <Card title="Endpoint install" icon="download" href="/cli/endpoint-install">
    Configure endpoint telemetry and collector service files.
  </Card>
  <Card title="Endpoint config" icon="gear" href="/cli/endpoint-config">
    Inspect endpoint configuration and validate destination settings.
  </Card>
</Columns>