Skip to content

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

Connect the endpoint when the wizard confirms Beacon Managed

shukieshah670b791cfde6
diff --git a/CLAUDE.md b/CLAUDE.md
index 6494a7ee..9b18b2b0 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -25,8 +25,8 @@ Do not recreate or depend on removed `asymptote` mirror trees. Keep new work foc
- Beacon is visibility-first endpoint telemetry for local AI agent runtimes, not a hosted policy service or general endpoint protection product.
- Preserve the local-only default. The public Beacon build must not require a hosted account, remote policy fetch, hosted dashboard, or external network dependency during normal hook execution, and hooks themselves never touch the network.
- `beacon login` is the account-identity channel for interactive users and is required by the interactive `beacon endpoint install` wizard. It uses browser PKCE against beacon.sh and stores the scoped CLI token only in `~/.beacon/auth/session.json` (0600 under a 0700 directory). Signing in alone never starts forwarding. User-mode `beacon endpoint connect` may send that token once to `POST /api/cli/enroll/account` to authorize minting a separate device ingest key; never copy the account token into endpoint config, Vector, hook environments, logs, or command output. System/root/package/MDM/CI/piped-stdin/dry-run installs stay noninteractive and account-free.
-- Beacon Managed forwarding (`cli/beacon/internal/endpoint/asymptote`, `beacon endpoint connect`, `beacon endpoint asymptote`) is Vector-shaped: Beacon writes local JSONL, Vector ships runtime lines only from the connection point forward and reads inventory from the beginning to establish the endpoint's current baseline, and the `bcn_device_*` key stays only in `<BaseDir>/asymptote/vector-secrets.json` via Vector's secret backend. The onboarding wizard preselects Managed but connect remains a separate action. Standard mode ships locally sanitized retained content; metadata-only uses local Vector transforms to remove prompts, responses, reasoning, tool arguments/results, command output, raw fields, diffs, inventory content, and MCP definitions before buffering/upload. Keep the ingest URL `https://`, the wire contract aligned with `beacon-ingest` (`/v1/ingest/{runtime,inventory}` and `/v1/ingest/health`), and do not add another endpoint network channel. The cloud-sandbox shuttle is the bounded exception: only with `BEACON_ORIGIN=cloud`, it can upload new runtime lines to GCS, S3, or the same Beacon ingest contract because no Vector/service manager/browser/persistent disk exists there.
-- `beacon endpoint install` has a full-screen onboarding wizard on interactive user TTYs. It signs in, preselects Beacon Managed, requires an explicit choice to opt out to Local, and asks Managed users to choose Standard or Metadata-only privacy. Accepting Managed still only records intent and prints `beacon endpoint connect`, so no telemetry moves during onboarding. Explicit `install --connect` still enrolls after installation. The wizard is skipped for system/root/CI/piped-stdin/dry-run or `BEACON_ONBOARDING=0`; those unattended paths must never gain an account or browser dependency. Legacy `BEACON_ONBOARDING_EMAIL`/`USAGE` submissions remain only for fleet compatibility. Implementation lives in `cli/beacon/internal/onboarding` and `cli/beacon/cmd/endpoint_onboarding.go`; keep `docs/cli/endpoint-onboarding.mdx` in sync.
+- Beacon Managed forwarding (`cli/beacon/internal/endpoint/asymptote`, `beacon endpoint connect`, `beacon endpoint asymptote`) is Vector-shaped: Beacon writes local JSONL, Vector ships runtime lines only from the connection point forward and reads inventory from the beginning to establish the endpoint's current baseline, and the `bcn_device_*` key stays only in `<BaseDir>/asymptote/vector-secrets.json` via Vector's secret backend. The onboarding wizard preselects Managed, and confirming it connects this endpoint in the same command once the local install has succeeded; an endpoint that is already enrolled is never re-enrolled, because enrollment rotates the device key. Standard mode ships locally sanitized retained content; metadata-only uses local Vector transforms to remove prompts, responses, reasoning, tool arguments/results, command output, raw fields, diffs, inventory content, and MCP definitions before buffering/upload. Keep the ingest URL `https://`, the wire contract aligned with `beacon-ingest` (`/v1/ingest/{runtime,inventory}` and `/v1/ingest/health`), and do not add another endpoint network channel. The cloud-sandbox shuttle is the bounded exception: only with `BEACON_ORIGIN=cloud`, it can upload new runtime lines to GCS, S3, or the same Beacon ingest contract because no Vector/service manager/browser/persistent disk exists there.
+- `beacon endpoint install` has a full-screen onboarding wizard on interactive user TTYs. It signs in, preselects Beacon Managed, requires an explicit choice to opt out to Local, and asks Managed users to choose Standard or Metadata-only privacy. Signing in alone still moves no telemetry. Confirming Managed does: the confirm screen states that it installs Beacon and starts forwarding, and names what the selected privacy mode sends, so that screen is the consent point. The managed destination is recorded only after enrollment succeeds, so a failed enrollment leaves a working local install, prints `beacon endpoint connect` as the retry, and re-offers the question on the next install. The onboarding record is written only after `lifecycle.Install` returns, because a profile written first left a failed install looking onboarded and silently skipped the wizard on the retry. Explicit `install --connect` is unchanged. The wizard is skipped for system/root/CI/piped-stdin/dry-run or `BEACON_ONBOARDING=0`; those unattended paths must never gain an account or browser dependency. Legacy `BEACON_ONBOARDING_EMAIL`/`USAGE` submissions remain only for fleet compatibility. Implementation lives in `cli/beacon/internal/onboarding` and `cli/beacon/cmd/endpoint_onboarding.go`; keep `docs/cli/endpoint-onboarding.mdx` in sync.
- Do not add dependency vulnerability scanning, OSV/GHSA lookups, package remediation, or other vulnerability-enforcement flows to the public hook path.
- Do not add broad runtime enforcement unless explicitly requested. Current control behavior is limited to hook-native approvals/denials exposed by supported agent runtimes.
- Keep destination support shaped like the existing local JSONL and customer-managed forwarding paths. Beacon may render supported packs or token-based endpoint forwarders, but should not add hosted SIEM dependencies or store third-party service credentials beyond the explicit supported configs. Elastic remains a file-tailing pack over local JSONL.
diff --git a/README.md b/README.md
index 55283933..3d6c1780 100644
--- a/README.md
+++ b/README.md
@@ -124,10 +124,11 @@ Or inspect the raw event stream:
```
> [!NOTE]
-> Local until connected: signing in or accepting the preselected Managed option
-> does not enable forwarding. The onboarding wizard records Standard or
-> Metadata-only privacy; `beacon endpoint connect` uses that choice, or
-> `--privacy-mode` overrides it.
+> Signing in does not enable forwarding. Confirming the preselected Beacon Managed
+> option does: the wizard says so on the confirm screen, names what your chosen
+> privacy mode sends, and connects the endpoint after the install succeeds. Choose
+> Local to keep everything on this machine, and disconnect any time with
+> `beacon endpoint disconnect`.
Inspect the account used during interactive setup:
diff --git a/cli/beacon/cmd/endpoint_install.go b/cli/beacon/cmd/endpoint_install.go
index 01c988a0..dd1568c6 100644
--- a/cli/beacon/cmd/endpoint_install.go
+++ b/cli/beacon/cmd/endpoint_install.go
@@ -105,13 +105,13 @@ func runEndpointInstall(cmd *cobra.Command, args []string) error {
}
// Asked once, on an interactive install, before anything is written to disk. Every
// non-interactive path (package postinstall, MDM, CI) is gated out inside.
- connectFromOnboarding, err := maybeRunOnboarding(cmd)
+ onboarded, err := maybeRunOnboarding(cmd)
if err != nil {
return err
}
- // A normal Managed selection records intent and prints the separate connect command.
- // Explicit --connect keeps its existing behavior and runs enrollment after install.
- connectAfterInstall := connectFromOnboarding || endpointOpts.connect
+ // Confirming Beacon Managed connects this endpoint; --connect does the same for
+ // the paths the wizard did not own.
+ connectAfterInstall := onboarded.Connect || endpointOpts.connect
result, err := lifecycle.Install(lifecycle.InstallOptions{
UserMode: endpointUserMode(),
LogPath: endpointOpts.logPath,
@@ -129,6 +129,14 @@ func runEndpointInstall(cmd *cobra.Command, args []string) error {
if err != nil {
return err
}
+ // Only now is the machine actually installed, so only now is it onboarded. The
+ // record used to be written before this call, which meant a failed install left
+ // a profile claiming otherwise and the retry silently skipped the wizard.
+ if onboarded.Persist != nil {
+ if err := onboarded.Persist(); err != nil {
+ fmt.Fprintf(cmd.ErrOrStderr(), "beacon: %v\n", err)
+ }
+ }
fmt.Printf("Endpoint config written to %s\n", result.ConfigPath)
fmt.Printf("Collector config written to %s\n", result.CollectorConfigPath)
fmt.Printf("Service definition written to %s\n", result.PlistPath)
diff --git a/cli/beacon/cmd/endpoint_onboarding.go b/cli/beacon/cmd/endpoint_onboarding.go
index 1925f9fa..42d906ac 100644
--- a/cli/beacon/cmd/endpoint_onboarding.go
+++ b/cli/beacon/cmd/endpoint_onboarding.go
@@ -84,13 +84,33 @@ func defaultOnboardingIsTTY() bool {
return isTerminal(os.Stdin) && isTerminal(os.Stdout)
}
+// onboardingOutcome is what interactive onboarding decided, for the installer to
+// act on once the local install has actually succeeded.
+//
+// Every field is the zero value on a gated path, so a package postinstall, an MDM
+// run, CI, a dry run and a redirected stdin all return an outcome that asks the
+// installer for nothing.
+type onboardingOutcome struct {
+ // Connect is true when the wizard confirmed Beacon Managed on an endpoint that
+ // is not already enrolled, so the installer should connect it after installing.
+ // An already-connected endpoint is deliberately excluded: enrollment rotates the
+ // device key, and rotating a working forwarder's key to re-learn a destination
+ // Beacon already knows would be a regression, not an improvement.
+ Connect bool
+ // Persist records the wizard's answers, and runs only after lifecycle.Install
+ // returns. Writing the profile first meant a failed install still left the
+ // machine marked onboarded, so the retry took the already-completed branch, said
+ // nothing, and never offered the destination again.
+ Persist func() error
+}
+
// maybeRunOnboarding runs the one-time account and destination wizard when this
-// install is interactive. It returns true only for explicit install --connect.
+// install is interactive.
//
// It is called from `endpoint install` after the --dry-run early return, so a dry run
// never prompts. An error returned here does stop the install: the prompt is a
// required step on an interactive terminal, and every refusal path names the opt-out.
-func maybeRunOnboarding(cmd *cobra.Command) (connect bool, err error) {
+func maybeRunOnboarding(cmd *cobra.Command) (onboardingOutcome, error) {
profile := onboardingLoad()
// Legacy pending attribution remains retryable, but new interactive installs use
@@ -98,13 +118,13 @@ func maybeRunOnboarding(cmd *cobra.Command) (connect bool, err error) {
if profile.Prompted() {
resendPendingOnboarding(&profile)
if profile.Onboarding.Destination != "" {
- return false, nil
+ return onboardingOutcome{}, nil
}
if !onboardingEnabledByEnv() {
- return false, nil
+ return onboardingOutcome{}, nil
}
if _, skipped := destinationSkipReason(profile); skipped {
- return false, nil
+ return onboardingOutcome{}, nil
}
return runAccountOnboarding(cmd, &profile, true)
}
@@ -113,16 +133,16 @@ func maybeRunOnboarding(cmd *cobra.Command) (connect bool, err error) {
// the only path that still uses the legacy submission endpoint.
if email, usage, ok := onboardingAnswersFromEnv(cmd.ErrOrStderr()); ok {
completeOnboarding(cmd, &profile, email, usage, nil, "")
- return false, nil
+ return onboardingOutcome{}, nil
}
if _, skipped := onboardingSkipReason(profile); skipped {
- return false, nil
+ return onboardingOutcome{}, nil
}
return runAccountOnboarding(cmd, &profile, false)
}
-func runAccountOnboarding(cmd *cobra.Command, profile *onboarding.Profile, destinationOnly bool) (bool, error) {
+func runAccountOnboarding(cmd *cobra.Command, profile *onboarding.Profile, destinationOnly bool) (onboardingOutcome, error) {
now := onboardingClock()
status := onboardingAccountInspect(now)
preset := ""
@@ -144,7 +164,7 @@ func runAccountOnboarding(cmd *cobra.Command, profile *onboarding.Profile, desti
}
result, err := onboardingRunWizard(onboardingStdin, cmd.OutOrStdout(), options)
if err != nil {
- return false, err
+ return onboardingOutcome{}, err
}
if result.NeedLogin {
session, err := onboardingAccountLogin(commandContext(cmd), account.LoginOptions{
@@ -153,10 +173,10 @@ func runAccountOnboarding(cmd *cobra.Command, profile *onboarding.Profile, desti
Now: onboardingClock,
})
if err != nil {
- return false, fmt.Errorf("Beacon sign-in is required for interactive setup: %w", err)
+ return onboardingOutcome{}, fmt.Errorf("Beacon sign-in is required for interactive setup: %w", err)
}
if err := onboardingAccountSave(*session); err != nil {
- return false, fmt.Errorf("store Beacon session: %w", err)
+ return onboardingOutcome{}, fmt.Errorf("store Beacon session: %w", err)
}
status = account.Status{SignedIn: true, User: session.User}
options.SignedIn = true
@@ -164,54 +184,71 @@ func runAccountOnboarding(cmd *cobra.Command, profile *onboarding.Profile, desti
options.DestinationOnly = true
result, err = onboardingRunWizard(onboardingStdin, cmd.OutOrStdout(), options)
if err != nil {
- return false, err
+ return onboardingOutcome{}, err
}
}
if !result.Completed {
- return false, onboarding.ErrWizardCancelled
+ return onboardingOutcome{}, onboarding.ErrWizardCancelled
}
- recordedDestination := result.Destination
privacyMode := ""
if result.Destination == onboarding.DestinationAsymptote {
privacyMode, err = managedprivacy.Normalize(result.PrivacyMode)
if err != nil {
- return false, err
+ return onboardingOutcome{}, err
}
}
- connectAfterInstall := endpointOpts.connect && result.Destination == onboarding.DestinationAsymptote
+
+ // Confirming Managed connects this endpoint, unless it already is one. An
+ // endpoint that is already enrolled keeps its device key and simply records the
+ // destination it has been using.
+ alreadyConnected := result.Destination == onboarding.DestinationAsymptote && !destinationAskable()
+ connectAfterInstall := result.Destination == onboarding.DestinationAsymptote && !alreadyConnected
+
+ recordedDestination := result.Destination
if connectAfterInstall {
- // Explicit --connect still records managed only after device enrollment
- // succeeds, preserving the existing retry behavior.
+ // Managed is recorded only once device enrollment succeeds, so a failed
+ // connect leaves the question open and the next install re-offers it. That
+ // is the mechanism `--connect` has always used; auto-connect inherits it.
recordedDestination = ""
}
- if profile.Onboarding.CompletedAt == "" {
- profile.Onboarding = onboarding.Onboarding{
- CompletedAt: onboardingClock().UTC().Format(time.RFC3339),
- Outcome: onboarding.OutcomeAuthenticated,
- Email: status.User.Email,
- BeaconVersion: version.GetVersion(),
- Destination: recordedDestination,
- PrivacyMode: privacyMode,
+
+ outcome := onboardingOutcome{Connect: connectAfterInstall}
+ email := status.User.Email
+ outcome.Persist = func() error {
+ if profile.Onboarding.CompletedAt == "" {
+ profile.Onboarding = onboarding.Onboarding{
+ CompletedAt: onboardingClock().UTC().Format(time.RFC3339),
+ Outcome: onboarding.OutcomeAuthenticated,
+ Email: email,
+ BeaconVersion: version.GetVersion(),
+ Destination: recordedDestination,
+ PrivacyMode: privacyMode,
+ }
+ profile.Pending = nil
+ } else {
+ profile.Onboarding.Destination = recordedDestination
+ profile.Onboarding.PrivacyMode = privacyMode
}
- profile.Pending = nil
- } else {
- profile.Onboarding.Destination = recordedDestination
- profile.Onboarding.PrivacyMode = privacyMode
- }
- if _, err := onboarding.EnsureInstallID(profile); err != nil {
- return false, fmt.Errorf("create onboarding install id: %w", err)
- }
- if err := onboardingSave(*profile); err != nil {
- return false, fmt.Errorf("record onboarding: %w", err)
+ if _, err := onboarding.EnsureInstallID(profile); err != nil {
+ return fmt.Errorf("create onboarding install id: %w", err)
+ }
+ if err := onboardingSave(*profile); err != nil {
+ return fmt.Errorf("record onboarding: %w", err)
+ }
+ return nil
}
- if result.Destination == onboarding.DestinationAsymptote && !connectAfterInstall {
- fmt.Fprintf(cmd.OutOrStdout(), "Beacon Managed selected with %s privacy. After installation, run `beacon endpoint connect`.\n", managedprivacy.Label(privacyMode))
- } else if result.Destination == onboarding.DestinationLocal {
+ switch {
+ case connectAfterInstall:
+ // The connect output that follows says where events now go; anticipating it
+ // here would only be wrong if enrollment then failed.
+ case result.Destination == onboarding.DestinationAsymptote:
+ fmt.Fprintf(cmd.OutOrStdout(), "Beacon Managed with %s privacy. This endpoint is already connected.\n", managedprivacy.Label(privacyMode))
+ case result.Destination == onboarding.DestinationLocal:
fmt.Fprintln(cmd.OutOrStdout(), "Local-only telemetry selected. Open it with `beacon traces`.")
}
- return connectAfterInstall, nil
+ return outcome, nil
}
// recordDestinationAsymptote stores the managed answer after explicit
diff --git a/cli/beacon/cmd/endpoint_onboarding_test.go b/cli/beacon/cmd/endpoint_onboarding_test.go
index 2eb32151..9886f9a2 100644
--- a/cli/beacon/cmd/endpoint_onboarding_test.go
+++ b/cli/beacon/cmd/endpoint_onboarding_test.go
@@ -157,10 +157,34 @@ func newOnboardingHarness(t *testing.T) *onboardingHarness {
return h
}
+// run is runOnboarding bound to this harness's command.
+func (h *onboardingHarness) run(t *testing.T) (bool, error) {
+ t.Helper()
+ return runOnboarding(t, h.cmd)
+}
+
+// runOnboarding runs onboarding and then performs the persistence step the
+// installer performs once lifecycle.Install has succeeded. Onboarding itself no
+// longer writes the profile: a record written before the install meant a failed
+// install still looked onboarded.
+func runOnboarding(t *testing.T, cmd *cobra.Command) (bool, error) {
+ t.Helper()
+ outcome, err := maybeRunOnboarding(cmd)
+ if err != nil {
+ return false, err
+ }
+ if outcome.Persist != nil {
+ if err := outcome.Persist(); err != nil {
+ return outcome.Connect, err
+ }
+ }
+ return outcome.Connect, nil
+}
+
func TestMaybeRunOnboardingPromptsOnInteractiveInstall(t *testing.T) {
h := newOnboardingHarness(t)
- if _, err := maybeRunOnboarding(h.cmd); err != nil {
+ if _, err := runOnboarding(t, h.cmd); err != nil {
t.Fatalf("maybeRunOnboarding returned error: %v", err)
}
if !h.asked {
@@ -173,12 +197,17 @@ func TestMaybeRunOnboardingPromptsOnInteractiveInstall(t *testing.T) {
t.Fatalf("saved = %+v, want one completed profile", h.saved)
}
if h.saved[0].Onboarding.Outcome != onboarding.OutcomeAuthenticated ||
- h.saved[0].Onboarding.Email != "[email protected]" ||
- h.saved[0].Onboarding.Destination != onboarding.DestinationAsymptote {
+ h.saved[0].Onboarding.Email != "[email protected]" {
t.Fatalf("saved account onboarding = %+v", h.saved[0].Onboarding)
}
- if !strings.Contains(h.stdout.String(), "beacon endpoint connect") {
- t.Fatalf("managed next step missing: %s", h.stdout.String())
+ // Managed is the preselected answer, and confirming it now connects the endpoint
+ // rather than printing a command for the user to run next. The destination stays
+ // unrecorded until that enrollment succeeds.
+ if h.saved[0].Onboarding.Destination != "" {
+ t.Fatalf("destination must not be recorded before enrollment succeeds: %q", h.saved[0].Onboarding.Destination)
+ }
+ if strings.Contains(h.stdout.String(), "beacon endpoint connect") {
+ t.Fatalf("the wizard should not tell the user to run connect when it is about to: %s", h.stdout.String())
}
if h.saved[0].InstallID == "" {
t.Fatalf("saved profile has no install ID")
@@ -250,7 +279,7 @@ func TestMaybeRunOnboardingStaysSilentWhenGated(t *testing.T) {
t.Fatalf("skip reason = %q, want %q", reason, tc.wantReason)
}
- if _, err := maybeRunOnboarding(h.cmd); err != nil {
+ if _, err := runOnboarding(t, h.cmd); err != nil {
t.Fatalf("maybeRunOnboarding returned error: %v", err)
}
if h.asked {
@@ -271,7 +300,7 @@ func TestMaybeRunOnboardingPropagatesPromptFailure(t *testing.T) {
h := newOnboardingHarness(t)
h.askErr = onboarding.ErrTooManyAttempts
- _, err := maybeRunOnboarding(h.cmd)
+ _, err := runOnboarding(t, h.cmd)
if err == nil {
t.Fatalf("maybeRunOnboarding returned nil, want the prompt failure to stop the install")
}
@@ -287,7 +316,7 @@ func TestInteractiveOnboardingSignsInWithoutLegacySubmission(t *testing.T) {
h := newOnboardingHarness(t)
h.accountStatus = account.Status{}
- if _, err := maybeRunOnboarding(h.cmd); err != nil {
+ if _, err := runOnboarding(t, h.cmd); err != nil {
t.Fatalf("maybeRunOnboarding returned error: %v", err)
}
if h.loginRuns != 1 {
@@ -306,7 +335,7 @@ func TestInteractiveOnboardingStopsWhenRequiredLoginFails(t *testing.T) {
h.accountStatus = account.Status{}
h.loginErr = errors.New("authentication service unavailable")
- _, err := maybeRunOnboarding(h.cmd)
+ _, err := runOnboarding(t, h.cmd)
if err == nil || !strings.Contains(err.Error(), "sign-in is required") {
t.Fatalf("error = %v", err)
}
@@ -324,7 +353,7 @@ func TestMaybeRunOnboardingResendsPendingSubmission(t *testing.T) {
Pending: &pending,
}
- if _, err := maybeRunOnboarding(h.cmd); err != nil {
+ if _, err := runOnboarding(t, h.cmd); err != nil {
t.Fatalf("maybeRunOnboarding returned error: %v", err)
}
if h.asked {
@@ -347,7 +376,7 @@ func TestMaybeRunOnboardingKeepsPendingWhenResendFails(t *testing.T) {
Pending: &pending,
}
- if _, err := maybeRunOnboarding(h.cmd); err != nil {
+ if _, err := runOnboarding(t, h.cmd); err != nil {
t.Fatalf("maybeRunOnboarding returned error: %v", err)
}
if len(h.saved) != 0 {
@@ -362,7 +391,7 @@ func TestMaybeRunOnboardingAcceptsEnvironmentAnswersHeadless(t *testing.T) {
t.Setenv(onboardingEnvEmail, " [email protected] ")
t.Setenv(onboardingEnvUsage, "work")
- if _, err := maybeRunOnboarding(h.cmd); err != nil {
+ if _, err := runOnboarding(t, h.cmd); err != nil {
t.Fatalf("maybeRunOnboarding returned error: %v", err)
}
if h.asked {
@@ -383,7 +412,7 @@ func TestMaybeRunOnboardingIgnoresInvalidEnvironmentAnswers(t *testing.T) {
t.Setenv(onboardingEnvEmail, "not-an-email")
t.Setenv(onboardingEnvUsage, "work")
- if _, err := maybeRunOnboarding(h.cmd); err != nil {
+ if _, err := runOnboarding(t, h.cmd); err != nil {
t.Fatalf("maybeRunOnboarding returned error: %v", err)
}
if len(h.sent) != 0 || h.asked {
@@ -400,7 +429,7 @@ func TestMaybeRunOnboardingEnvironmentAnswersRespectOptOut(t *testing.T) {
t.Setenv(onboardingEnvEmail, "[email protected]")
t.Setenv(onboardingEnvUsage, "work")
- if _, err := maybeRunOnboarding(h.cmd); err != nil {
+ if _, err := runOnboarding(t, h.cmd); err != nil {
t.Fatalf("maybeRunOnboarding returned error: %v", err)
}
if len(h.sent) != 0 {
@@ -416,7 +445,7 @@ func TestPreviouslyOnboardedDestinationUpgradeRespectsOptOut(t *testing.T) {
}
t.Setenv(onboardingEnvEnabled, "0")
- if connect, err := maybeRunOnboarding(h.cmd); err != nil || connect {
+ if connect, err := runOnboarding(t, h.cmd); err != nil || connect {
t.Fatalf("connect=%t err=%v", connect, err)
}
if h.asked || h.standaloneAsked || h.loginRuns != 0 || len(h.saved) != 0 {
@@ -607,11 +636,14 @@ func TestRetryPendingOnboardingIsSilentWithNothingQueued(t *testing.T) {
}
}
-func TestMaybeRunOnboardingRecordsLocalOrManagedIntent(t *testing.T) {
+func TestMaybeRunOnboardingConnectsManagedAndRecordsLocal(t *testing.T) {
+ // An endpoint that is already enrolled is not asked and is not re-enrolled:
+ // enrollment rotates the device key, so reconnecting a working forwarder to
+ // re-learn a destination Beacon already has would break it, not improve it.
h := newOnboardingHarness(t)
h.askable = false
- if connect, err := maybeRunOnboarding(h.cmd); err != nil || connect {
- t.Fatalf("connect=%t err=%v", connect, err)
+ if connect, err := runOnboarding(t, h.cmd); err != nil || connect {
+ t.Fatalf("an already-connected endpoint must not be re-enrolled: connect=%t err=%v", connect, err)
}
if len(h.offered) != 1 || h.offered[0].AskDestination {
t.Fatalf("the destination question must not be asked on a connected endpoint: %+v", h.offered)
@@ -620,27 +652,34 @@ func TestMaybeRunOnboardingRecordsLocalOrManagedIntent(t *testing.T) {
t.Fatalf("connected endpoint destination = %q, want managed", got)
}
+ // Confirming Managed on a fresh endpoint connects it in the same command.
h = newOnboardingHarness(t)
h.askable = true
h.answers.DestinationAsked = true
h.answers.Destination = onboarding.DestinationAsymptote
h.wizardPrivacyMode = "metadata-only"
- connect, err := maybeRunOnboarding(h.cmd)
- if err != nil || connect {
- t.Fatalf("managed intent should leave connect as a separate step: connect=%t err=%v", connect, err)
+ connect, err := runOnboarding(t, h.cmd)
+ if err != nil || !connect {
+ t.Fatalf("confirming managed should connect this endpoint: connect=%t err=%v", connect, err)
}
if !h.offered[0].AskDestination || !h.offered[0].OfferAsymptote {
t.Fatalf("wizard should offer local and managed destinations: %+v", h.offered[0])
}
- if got := h.saved[len(h.saved)-1].Onboarding.Destination; got != onboarding.DestinationAsymptote {
- t.Fatalf("managed intent was not recorded, got %q", got)
+ // The privacy answer is recorded now, because connect reads it back. The
+ // destination is not, because enrollment has not happened yet.
+ saved := h.saved[len(h.saved)-1].Onboarding
+ if saved.Destination != "" {
+ t.Fatalf("managed must not be recorded before enrollment succeeds, got %q", saved.Destination)
+ }
+ if saved.PrivacyMode != "metadata_only" {
+ t.Fatalf("privacy mode must be recorded for connect to read: %q", saved.PrivacyMode)
}
h = newOnboardingHarness(t)
h.askable = true
h.answers.DestinationAsked = true
h.answers.Destination = onboarding.DestinationLocal
- if connect, _ := maybeRunOnboarding(h.cmd); connect {
+ if connect, _ := runOnboarding(t, h.cmd); connect {
t.Fatal("local selection must not connect")
}
if got := h.saved[len(h.saved)-1].Onboarding.Destination; got != onboarding.DestinationLocal {
@@ -655,7 +694,7 @@ func TestDestinationQuestionHidesAsymptoteWhenOptedOut(t *testing.T) {
t.Setenv(managedIngestEnvEnabled, "0")
h.answers.DestinationAsked = true
h.answers.Destination = onboarding.DestinationLocal
- if connect, err := maybeRunOnboarding(h.cmd); err != nil || connect {
+ if connect, err := runOnboarding(t, h.cmd); err != nil || connect {
t.Fatalf("connect=%t err=%v", connect, err)
}
if len(h.offered) != 1 || !h.offered[0].AskDestination || h.offered[0].OfferAsymptote {
@@ -667,7 +706,7 @@ func TestDestinationQuestionHidesAsymptoteWhenOptedOut(t *testing.T) {
t.Setenv(managedIngestEnvEnabled, "0")
h.loaded = onboarding.Profile{InstallID: "abc", Onboarding: onboarding.Onboarding{CompletedAt: "2026-08-01T00:00:00Z"}}
h.standaloneAnswer = onboarding.DestinationLocal
- if _, err := maybeRunOnboarding(h.cmd); err != nil || !h.standaloneAsked || h.standaloneOffered {
+ if _, err := runOnboarding(t, h.cmd); err != nil || !h.standaloneAsked || h.standaloneOffered {
t.Fatalf("standalone question should be asked without the Asymptote row: err=%v asked=%t offered=%t", err, h.standaloneAsked, h.standaloneOffered)
}
if got := h.saved[len(h.saved)-1].Onboarding.Destination; got != onboarding.DestinationLocal {
@@ -680,9 +719,9 @@ func TestDestinationAskedOnceToPreviouslyOnboardedMachine(t *testing.T) {
h.askable = true
h.loaded = onboarding.Profile{InstallID: "abc", Onboarding: onboarding.Onboarding{CompletedAt: "2026-08-01T00:00:00Z", Outcome: onboarding.OutcomeSubmitted, Email: "[email protected]", Usage: onboarding.UsageWork}}
h.standaloneAnswer = onboarding.DestinationAsymptote
- connect, err := maybeRunOnboarding(h.cmd)
- if err != nil || connect {
- t.Fatalf("connect=%t err=%v", connect, err)
+ connect, err := runOnboarding(t, h.cmd)
+ if err != nil || !connect {
+ t.Fatalf("answering managed should connect this endpoint: connect=%t err=%v", connect, err)
}
if h.asked {
t.Fatal("the signup questions must not be asked again")
@@ -690,8 +729,8 @@ func TestDestinationAskedOnceToPreviouslyOnboardedMachine(t *testing.T) {
if !h.standaloneAsked || !h.standaloneOffered {
t.Fatalf("the destination question should be asked once, with the Asymptote row: asked=%t offered=%t", h.standaloneAsked, h.standaloneOffered)
}
- if len(h.saved) != 1 || h.saved[0].Onboarding.Destination != onboarding.DestinationAsymptote {
- t.Fatalf("managed intent must be recorded before the separate connect step: %+v", h.saved)
+ if len(h.saved) != 1 || h.saved[0].Onboarding.Destination != "" {
+ t.Fatalf("managed must be recorded only after enrollment succeeds: %+v", h.saved)
}
// Local is recorded at once.
@@ -699,7 +738,7 @@ func TestDestinationAskedOnceToPreviouslyOnboardedMachine(t *testing.T) {
h.askable = true
h.loaded = onboarding.Profile{InstallID: "abc", Onboarding: onboarding.Onboarding{CompletedAt: "2026-08-01T00:00:00Z"}}
h.standaloneAnswer = onboarding.DestinationLocal
- if connect, _ := maybeRunOnboarding(h.cmd); connect || !h.standaloneAsked {
+ if connect, _ := runOnboarding(t, h.cmd); connect || !h.standaloneAsked {
t.Fatalf("connect=%t asked=%t", connect, h.standaloneAsked)
}
if got := h.saved[len(h.saved)-1].Onboarding.Destination; got != onboarding.DestinationLocal {
@@ -710,7 +749,7 @@ func TestDestinationAskedOnceToPreviouslyOnboardedMachine(t *testing.T) {
h = newOnboardingHarness(t)
h.askable = true
h.loaded = onboarding.Profile{InstallID: "abc", Onboarding: onboarding.Onboarding{CompletedAt: "2026-08-01T00:00:00Z", Destination: onboarding.DestinationLocal}}
- if connect, _ := maybeRunOnboarding(h.cmd); connect || h.standaloneAsked {
+ if connect, _ := runOnboarding(t, h.cmd); connect || h.standaloneAsked {
t.Fatalf("a recorded destination must not be asked again: connect=%t asked=%t", connect, h.standaloneAsked)
}
@@ -719,14 +758,14 @@ func TestDestinationAskedOnceToPreviouslyOnboardedMachine(t *testing.T) {
h.askable = true
h.loaded = onboarding.Profile{InstallID: "abc", Onboarding: onboarding.Onboarding{CompletedAt: "2026-08-01T00:00:00Z"}}
onboardingIsTTY = func() bool { return false }
- if connect, _ := maybeRunOnboarding(h.cmd); connect || h.standaloneAsked {
+ if connect, _ := runOnboarding(t, h.cmd); connect || h.standaloneAsked {
t.Fatal("no terminal, no question")
}
h = newOnboardingHarness(t)
h.askable = true
h.loaded = onboarding.Profile{InstallID: "abc", Onboarding: onboarding.Onboarding{CompletedAt: "2026-08-01T00:00:00Z"}}
t.Setenv("CI", "1")
- if connect, _ := maybeRunOnboarding(h.cmd); connect || h.standaloneAsked {
+ if connect, _ := runOnboarding(t, h.cmd); connect || h.standaloneAsked {
t.Fatal("CI never sees the question")
}
// An upgraded endpoint that is already connected keeps the legacy skip
@@ -734,34 +773,47 @@ func TestDestinationAskedOnceToPreviouslyOnboardedMachine(t *testing.T) {
h = newOnboardingHarness(t)
h.askable = false
h.loaded = onboarding.Profile{InstallID: "abc", Onboarding: onboarding.Onboarding{CompletedAt: "2026-08-01T00:00:00Z"}}
- if connect, _ := maybeRunOnboarding(h.cmd); connect || h.standaloneAsked || h.loginRuns != 0 || len(h.saved) != 0 {
+ if connect, _ := runOnboarding(t, h.cmd); connect || h.standaloneAsked || h.loginRuns != 0 || len(h.saved) != 0 {
t.Fatalf("connected reinstall prompted or persisted: connect=%t asked=%t login=%d saved=%+v", connect, h.standaloneAsked, h.loginRuns, h.saved)
}
}
-func TestManagedDestinationIsRecordedAsIntent(t *testing.T) {
+func TestManagedDestinationIsRecordedOnlyAfterConnectSucceeds(t *testing.T) {
h := newOnboardingHarness(t)
h.askable = true
h.answers.DestinationAsked = true
h.answers.Destination = onboarding.DestinationAsymptote
h.wizardPrivacyMode = "metadata-only"
- if connect, err := maybeRunOnboarding(h.cmd); err != nil || connect {
+ if connect, err := runOnboarding(t, h.cmd); err != nil || !connect {
t.Fatalf("connect=%t err=%v", connect, err)
}
afterPrompt := h.saved[len(h.saved)-1]
- if afterPrompt.Onboarding.Destination != onboarding.DestinationAsymptote {
- t.Fatalf("managed intent = %q", afterPrompt.Onboarding.Destination)
+ if afterPrompt.Onboarding.Destination != "" {
+ t.Fatalf("destination recorded before enrollment: %q", afterPrompt.Onboarding.Destination)
}
if afterPrompt.Onboarding.PrivacyMode != "metadata_only" {
t.Fatalf("managed privacy = %q", afterPrompt.Onboarding.PrivacyMode)
}
- if !strings.Contains(h.stdout.String(), "beacon endpoint connect") {
- t.Fatalf("managed next step missing: %s", h.stdout.String())
+
+ // An enrollment that never succeeded leaves the destination open, so the next
+ // install asks again and retries rather than silently doing nothing. This is the
+ // retry path, and it is the reason the destination is written last.
+ retry := newOnboardingHarness(t)
+ retry.loaded = afterPrompt
+ retry.askable = true
+ retry.standaloneAnswer = onboarding.DestinationAsymptote
+ if connect, err := retry.run(t); err != nil || !connect || !retry.standaloneAsked {
+ t.Fatalf("an unconnected managed endpoint should re-offer and retry: connect=%t asked=%t err=%v", connect, retry.standaloneAsked, err)
}
+
+ // Once enrollment has succeeded, recordDestinationAsymptote fills the destination
+ // in and the question is never asked again.
+ connected := afterPrompt
+ connected.Onboarding.Destination = onboarding.DestinationAsymptote
h2 := newOnboardingHarness(t)
- h2.loaded = afterPrompt
- if connect, err := maybeRunOnboarding(h2.cmd); err != nil || connect || h2.asked || h2.standaloneAsked {
- t.Fatalf("recorded intent prompted again: connect=%t err=%v", connect, err)
+ h2.loaded = connected
+ if connect, err := h2.run(t); err != nil || connect || h2.asked || h2.standaloneAsked {
+ t.Fatalf("a recorded managed destination prompted again: connect=%t err=%v", connect, err)
}
}
@@ -773,7 +825,7 @@ func TestInstallConnectFlagSkipsDestinationQuestion(t *testing.T) {
h.askable = true
endpointOpts.connect = true
t.Cleanup(func() { endpointOpts.connect = false })
- if connect, err := maybeRunOnboarding(h.cmd); err != nil || !connect {
+ if connect, err := runOnboarding(t, h.cmd); err != nil || !connect {
t.Fatalf("connect=%t err=%v", connect, err)
}
if len(h.offered) != 1 || h.offered[0].AskDestination {
@@ -786,7 +838,7 @@ func TestInstallConnectFlagSkipsDestinationQuestion(t *testing.T) {
h = newOnboardingHarness(t)
h.askable = true
h.loaded = onboarding.Profile{InstallID: "abc", Onboarding: onboarding.Onboarding{CompletedAt: "2026-08-01T00:00:00Z"}}
- if connect, err := maybeRunOnboarding(h.cmd); err != nil || !connect || !h.standaloneAsked {
+ if connect, err := runOnboarding(t, h.cmd); err != nil || !connect || !h.standaloneAsked {
t.Fatalf("connect=%t err=%v asked=%t", connect, err, h.standaloneAsked)
}
@@ -841,3 +893,52 @@ func TestEndpointOnboardingShowsDestination(t *testing.T) {
t.Fatalf("privacy missing:\n%s", h.stdout.String())
}
}
+
+// Onboarding must persist nothing until the install it is onboarding has actually
+// succeeded.
+//
+// The profile used to be written inside the wizard, before lifecycle.Install ran.
+// An install that then failed left a record saying the machine was onboarded, so
+// the retry took the already-completed branch, printed nothing, and never offered
+// the destination again -- leaving the user with a recorded intent and no endpoint.
+func TestOnboardingPersistsNothingUntilTheInstallSucceeds(t *testing.T) {
+ h := newOnboardingHarness(t)
+ h.askable = true
+
+ outcome, err := maybeRunOnboarding(h.cmd)
+ if err != nil {
+ t.Fatalf("maybeRunOnboarding returned error: %v", err)
+ }
+ if !h.asked {
+ t.Fatal("expected the wizard to run")
+ }
+ if outcome.Persist == nil {
+ t.Fatal("a completed wizard must hand the installer a record to persist")
+ }
+ // runEndpointInstall calls Persist only after lifecycle.Install returns nil.
+ // Stopping here is what a failed install looks like.
+ if len(h.saved) != 0 {
+ t.Fatalf("onboarding wrote a profile before the install succeeded: %+v", h.saved)
+ }
+
+ // Once the install succeeds, the record lands. (Done before the retry harness
+ // below, which rebinds the package-level save hook to itself.)
+ if err := outcome.Persist(); err != nil {
+ t.Fatalf("persist after a successful install: %v", err)
+ }
+ if len(h.saved) != 1 || !h.saved[0].Prompted() {
+ t.Fatalf("saved = %+v, want one completed profile once the install succeeded", h.saved)
+ }
+
+ // After a failed install nothing was persisted, so the next install reloads an
+ // unprompted machine and asks again instead of silently skipping.
+ retry := newOnboardingHarness(t)
+ retry.askable = true
+ retry.loaded = onboarding.Profile{}
+ if _, err := maybeRunOnboarding(retry.cmd); err != nil {
+ t.Fatalf("retry returned error: %v", err)
+ }
+ if !retry.asked {
+ t.Fatal("a machine whose install failed must be asked again on the next install")
+ }
+}
diff --git a/cli/beacon/internal/onboarding/wizard.go b/cli/beacon/internal/onboarding/wizard.go
index ee6b3876..d85786a4 100644
--- a/cli/beacon/internal/onboarding/wizard.go
+++ b/cli/beacon/internal/onboarding/wizard.go
@@ -200,8 +200,8 @@ func (m wizardModel) View() string {
body = strings.Join(rows, "\n")
case managedDisclosureScreen:
title = "Beacon Managed sends new telemetry to beacon.sh"
- body = wizardWarn.Render("Nothing is forwarded by signing in or completing this wizard.") +
- "\n\nAfter installation, run `beacon endpoint connect`. Once connected, a local Vector forwarder sends new events to beacon.sh over HTTPS." +
+ body = wizardWarn.Render("Nothing is forwarded by signing in.") +
+ "\n\nBeacon installs, then connects this machine: a device key is minted and a local Vector forwarder starts sending new events to beacon.sh over HTTPS." +
"\n\nRuntime events recorded before you connect stay on this machine. The inventory snapshot -- which agent runtimes, skills, and MCP servers are installed here -- uploads once so the dashboard has this endpoint's baseline." +
"\n\nStop any time with `beacon endpoint disconnect`."
case privacyScreen:
@@ -217,12 +217,13 @@ func (m wizardModel) View() string {
}
body = strings.Join(rows, "\n")
case confirmScreen:
- title = "Ready to install"
+ title = "Ready to set up Beacon"
label, _ := destinationCopy(m.result.Destination)
body = "Account: " + m.options.Email + "\nDestination: " + label
if m.result.Destination == DestinationAsymptote {
body += "\nPrivacy: " + managedprivacy.Label(m.result.PrivacyMode) +
- "\n\nNext step after install: beacon endpoint connect"
+ "\n\n" + wizardWarn.Render("Confirming installs Beacon and starts forwarding new events to beacon.sh.") +
+ "\n\n" + privacySends(m.result.PrivacyMode)
} else {
body += "\n\nYour telemetry stays on this machine."
}
@@ -231,7 +232,7 @@ func (m wizardModel) View() string {
card := wizardAccent.Render("B E A C O N") + "\n\n" +
wizardAccent.Render(title) + "\n\n" +
lipgloss.NewStyle().Width(contentWidth).Render(body) + "\n\n" +
- wizardDim.Render(wizardHint(m.screen))
+ wizardDim.Render(m.hint())
return lipgloss.NewStyle().Padding(1, 3).Render(card)
}
@@ -281,6 +282,23 @@ func privacyIndex(mode string) int {
return 0
}
+// privacySends states, in the present tense, what the selected mode puts on the
+// wire. The confirm screen is where forwarding is authorized, so it has to name what
+// leaves this machine rather than point at a command to run later.
+func privacySends(mode string) string {
+ if mode == managedprivacy.MetadataOnly {
+ return "Metadata only: prompts, responses, reasoning, tool arguments and results, command output and diffs stay on this machine."
+ }
+ return "Standard: the locally sanitized event, including prompts and tool activity."
+}
+
+func (m wizardModel) hint() string {
+ if m.screen == confirmScreen && m.result.Destination == DestinationAsymptote {
+ return "enter install and connect · esc cancel"
+ }
+ return wizardHint(m.screen)
+}
+
func wizardHint(screen wizardScreen) string {
switch screen {
case destinationScreen:
diff --git a/cli/beacon/internal/onboarding/wizard_test.go b/cli/beacon/internal/onboarding/wizard_test.go
index 6366efca..77eb637b 100644
--- a/cli/beacon/internal/onboarding/wizard_test.go
+++ b/cli/beacon/internal/onboarding/wizard_test.go
@@ -83,8 +83,11 @@ func TestManagedWizardRequiresDisclosureConfirmation(t *testing.T) {
view := strings.Join(strings.Fields(model.View()), " ")
for _, want := range []string{
"sends new telemetry to beacon.sh",
- "Nothing is forwarded",
- "beacon endpoint connect",
+ "Nothing is forwarded by signing in",
+ // Confirming now connects, so the disclosure describes that rather than
+ // naming a command the user is expected to run afterwards.
+ "Beacon installs, then connects this machine",
+ "beacon endpoint disconnect",
// The disclosure has to describe what actually ships. The runtime source is
// read_from = "end", so pre-connect runtime events stay local -- but the
// inventory source is read_from = "beginning", so the existing snapshot does
@@ -240,3 +243,53 @@ func TestWizardHasNoGlobalQuitKey(t *testing.T) {
t.Fatal("esc must still cancel the wizard")
}
}
+
+// The confirm screen is where forwarding is authorized, so it has to name the
+// action. It used to say "Next step after install: beacon endpoint connect", which
+// stopped being true once confirming did the connecting.
+func TestConfirmScreenNamesWhatConfirmingStarts(t *testing.T) {
+ for mode, wantSends := range map[string]string{
+ "standard": "including prompts and tool activity",
+ "metadata_only": "stay on this machine",
+ } {
+ model := newWizardModel(WizardOptions{
+ SignedIn: true,
+ Email: "[email protected]",
+ OfferManaged: true,
+ DestinationOnly: true,
+ PresetDestination: DestinationAsymptote,
+ PresetPrivacyMode: mode,
+ })
+ model.width, model.height = 100, 30
+ model.screen = confirmScreen
+ model.result.Destination = DestinationAsymptote
+ model.result.PrivacyMode = mode
+
+ view := strings.Join(strings.Fields(model.View()), " ")
+ for _, want := range []string{
+ "Confirming installs Beacon and starts forwarding new events to beacon.sh.",
+ wantSends,
+ "enter install and connect",
+ } {
+ if !strings.Contains(view, want) {
+ t.Fatalf("confirm screen for %s missing %q:\n%s", mode, want, view)
+ }
+ }
+ if strings.Contains(view, "Next step after install") {
+ t.Fatalf("confirm screen still defers connect to a later command:\n%s", view)
+ }
+ }
+
+ // Local says the opposite, and its hint stays plain.
+ local := newWizardModel(WizardOptions{SignedIn: true, Email: "[email protected]", OfferManaged: true})
+ local.width, local.height = 100, 30
+ local.screen = confirmScreen
+ local.result.Destination = DestinationLocal
+ view := strings.Join(strings.Fields(local.View()), " ")
+ if !strings.Contains(view, "Your telemetry stays on this machine.") {
+ t.Fatalf("local confirm screen = %s", view)
+ }
+ if strings.Contains(view, "install and connect") {
+ t.Fatalf("local confirm screen must not offer to connect: %s", view)
+ }
+}
diff --git a/docs/changelog/cli.mdx b/docs/changelog/cli.mdx
index 69c4767e..676ff5c0 100644
--- a/docs/changelog/cli.mdx
+++ b/docs/changelog/cli.mdx
@@ -13,6 +13,19 @@ Stay up to date with the latest changes to the Agent Beacon CLI.
### Unreleased
+- **Choosing Beacon Managed now connects the endpoint** · Confirming Managed in the
+ install wizard installs Beacon and then enrolls the device and starts the
+ forwarder, instead of printing `beacon endpoint connect` for you to run yourself.
+ The confirm screen states that forwarding starts and names what the selected
+ privacy mode sends. An endpoint that is already enrolled is never re-enrolled,
+ since enrollment rotates its device key. A failed enrollment leaves a working local
+ install, prints the retry command, and re-offers the question on the next install.
+- **A failed install no longer marks the machine onboarded** · The onboarding record
+ was written before `lifecycle.Install` ran, so an install that then failed left a
+ profile saying setup was complete: the retry skipped the wizard silently and never
+ offered the destination again. The record is now written only after the install
+ succeeds.
+
- **Clearer first-run onboarding** · The destination screen now says what Beacon
Managed gives you rather than how it works: one searchable history across every
agent, unlimited retention, token and usage analytics, and no backend to run. The
diff --git a/docs/cli/endpoint-install.mdx b/docs/cli/endpoint-install.mdx
index 3a264400..354cb514 100644
--- a/docs/cli/endpoint-install.mdx
+++ b/docs/cli/endpoint-install.mdx
@@ -54,12 +54,13 @@ signs in through beacon.sh, then asks where this machine's telemetry should go:
| Answer | What happens |
|--------|--------------|
-| Beacon Managed (default) | Shows what will be sent, asks for Standard or Metadata-only privacy, records both choices, and prints `beacon endpoint connect` as a separate next step. Nothing is forwarded during the wizard. |
+| Beacon Managed (default) | Shows what will be sent, asks for Standard or Metadata-only privacy, then installs Beacon and connects this endpoint. The confirm screen states that forwarding starts before you accept. An endpoint that is already enrolled keeps its device key and is not re-enrolled. |
| Local only | Explicitly opts out of managed forwarding. Nothing is sent anywhere. |
-`--connect` presets Beacon Managed and attempts the connect flow after installation.
-If connect fails, the completed local install still exits successfully and prints
-`beacon endpoint connect` as the retry command. Automation should verify
+`--connect` presets Beacon Managed and skips the destination question. Whether
+connect was chosen in the wizard or by the flag, a failed enrollment leaves the
+completed local install exiting successfully and prints `beacon endpoint connect` as
+the retry command. Automation should verify
`.managed_ingest.connected` with `beacon endpoint status --json`.
`BEACON_MANAGED_INGEST=0` hides the managed answer. The wizard is never shown
for system/root, package, MDM, CI, dry-run, or redirected-input installs.
diff --git a/docs/cli/endpoint-onboarding.mdx b/docs/cli/endpoint-onboarding.mdx
index 3ee17b98..1fff76df 100644
--- a/docs/cli/endpoint-onboarding.mdx
+++ b/docs/cli/endpoint-onboarding.mdx
@@ -37,26 +37,33 @@ to opt out of managed forwarding.
Choosing Beacon Managed shows a separate disclosure naming exactly what leaves the
machine: runtime events recorded before you connect stay local, while the inventory
snapshot of which agent runtimes, skills, and MCP servers are installed uploads once
-so the dashboard has a baseline for the endpoint. Forwarding starts only after you
-run:
-
-```bash
-beacon endpoint connect
-```
+so the dashboard has a baseline for the endpoint.
Standard forwards the complete locally sanitized event. Metadata only strips retained
prompts, responses, reasoning, tool arguments/results, command output, raw fields,
diffs, and optional inventory content locally before upload. See
[`beacon endpoint connect`](/cli/endpoint-connect#privacy-modes) for the exact contract.
-Completing the wizard records managed intent and prints that next step; it does not
-connect automatically. Pre-connect runtime history 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 explicit
-`beacon endpoint install --connect` flag remains the exception: it presets Managed
-and attempts device enrollment after installation. If that enrollment fails, the
+Confirming Beacon Managed connects this endpoint in the same command, after the
+local install succeeds. The confirm screen says so before you press enter, and names
+what the selected privacy mode sends, so it is the point at which 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.
+
+Pre-connect runtime history 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 and prints `beacon endpoint connect` as the retry
-command; verify forwarding with `beacon endpoint status --json`.
+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.
+
+The explicit `beacon endpoint install --connect` flag is unchanged: it presets Managed
+and skips the destination question.
The wizard never appears non-interactively. Package postinstall scripts, MDM
deployments, `--system` installs, CI, `--dry-run`, and any piped or redirected stdin
diff --git a/docs/get-started/quickstart.mdx b/docs/get-started/quickstart.mdx
index 88219e53..ef71d5ad 100644
--- a/docs/get-started/quickstart.mdx
+++ b/docs/get-started/quickstart.mdx
@@ -64,15 +64,18 @@ Send your Beacon telemetry to the hosted service for:
- analytics
- access from anywhere
-Interactive installation signs in and preselects Managed. Connect the endpoint
-after reviewing the privacy choice:
+Interactive installation signs in, preselects Managed, and asks you to review the
+privacy choice. Confirming installs Beacon and connects this endpoint in the same
+command, using the signed-in CLI account to authorize a separate device ingest key
+with no second browser approval.
+
+If you chose Local during setup, or enrollment did not succeed, connect later with:
```bash
beacon endpoint connect
```
-The existing CLI account authorizes a separate device ingest key; there is no
-second browser approval. Use `--privacy-mode metadata-only` to override Standard.
+Use `--privacy-mode metadata-only` to override Standard.
## 3. Run an agent
diff --git a/docs/platforms/linux-deployment-profile.mdx b/docs/platforms/linux-deployment-profile.mdx
index c2ce3368..2c7820c4 100644
--- a/docs/platforms/linux-deployment-profile.mdx
+++ b/docs/platforms/linux-deployment-profile.mdx
@@ -94,6 +94,8 @@ The only outbound connections Beacon ever makes, for an egress allowlist:
| Host | When | Suppress with |
|---|---|---|
| `auth.asymptotelabs.ai` | Once per machine, interactive install only | `BEACON_ONBOARDING=0` (already skipped for `--system` and package installs) |
+| `beacon.sh` | Interactive install only: browser sign-in, and the device enrollment that follows when Beacon Managed is confirmed | `BEACON_MANAGED_INGEST=0` hides the managed answer; `BEACON_ONBOARDING=0` skips the wizard entirely |
+| Your ingest host | Continuously, only on an endpoint connected to Beacon Managed | `beacon endpoint disconnect`, or never connecting |
| `api.github.com`, `github.com` | Version check and self-update | Off by default; leave it off and deploy through your config management |
```bash