Skip to content

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

Revamp interactive endpoint onboarding

Justin D'Souzab656bce5a949
diff --git a/CLAUDE.md b/CLAUDE.md
index 10b0cfc7..dcb5b545 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -24,9 +24,9 @@ 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 optional account-identity channel for interactive users. It uses browser PKCE against beacon.sh, stores the scoped CLI token only in `~/.beacon/auth/session.json` (0600 under a 0700 directory), and is separate from endpoint enrollment: signing in alone never starts forwarding or sends telemetry. Keep account credentials out of endpoint config, hook environments, logs, and command output.
+- `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, stores the scoped CLI token only in `~/.beacon/auth/session.json` (0600 under a 0700 directory), and is separate from endpoint enrollment: signing in alone never starts forwarding or sends telemetry. System/root/package/MDM/CI/piped-stdin/dry-run installs stay noninteractive and account-free. Keep account credentials out of endpoint config, hook environments, logs, and command output.
- Asymptote Managed forwarding (`cli/beacon/internal/endpoint/asymptote`, `beacon endpoint connect`, `beacon endpoint asymptote`) is opt-in and Vector-shaped: Beacon writes local JSONL, Vector ships new lines after browser approval, and the `bcn_device_*` key stays only in `<BaseDir>/asymptote/vector-secrets.json` via Vector's secret backend. 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 Asymptote ingest contract because no Vector/service manager/browser/persistent disk exists there.
-- `beacon endpoint install` has a bounded onboarding channel for open-source attribution and destination choice. It is interactive TTY only, once per machine, skipped for system/root/CI/piped-stdin/dry-run or `BEACON_ONBOARDING=0`, and failures never fail install. It sends install context only, never prompts, events, file content, or command output. Implementation lives in `cli/beacon/internal/onboarding` and `cli/beacon/cmd/endpoint_onboarding.go`; keep `docs/cli/endpoint-onboarding.mdx` in sync with payload changes and do not copy the field list into the README.
+- `beacon endpoint install` has a full-screen onboarding wizard on interactive user TTYs. It signs in, then offers Local (default) or Beacon Managed; Managed records intent and prints `beacon endpoint connect` as a separate next step, while 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.
- 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 bf25f56d..f7f6a717 100644
--- a/README.md
+++ b/README.md
@@ -39,13 +39,15 @@ Beacon is an open-source memory layer for AI coding agents that learns from your
- **Knowledge that compounds** - workflows, corrections, debugging patterns, and repo conventions that survive beyond a single session
- **Shared agent memory** - reviewed knowledge future agents can retrieve through MCP or Agent Skills
- **Exact session replay** - prompts, responses, tools, commands, edits, approvals, MCP activity, and tokens in one trace
-- **Local-first portability** - durable JSONL, no account, and no harness lock-in
+- **Local-first portability** - durable JSONL, explicit destinations, and no harness lock-in
---
## 🚀 Quick Start
-Beacon is open source, local-first, and requires no account.
+Beacon is open source and local-first. Interactive endpoint setup signs in through
+beacon.sh, then defaults to keeping telemetry on the machine. System, package, MDM,
+and CI installation paths remain noninteractive and account-free.
### 1. Install Beacon
@@ -121,12 +123,11 @@ Or inspect the raw event stream:
```
> [!NOTE]
-> Local by default: no account, no API key, and nothing leaves your machine unless you configure it to.
+> Local by default: signing in does not enable forwarding, and nothing leaves your machine unless you configure it to.
-Account sign-in is a separate, optional step and does not enable telemetry forwarding:
+Inspect the account used during interactive setup:
```bash
-beacon login
beacon whoami
```
diff --git a/cli/beacon/cmd/endpoint_install.go b/cli/beacon/cmd/endpoint_install.go
index 29777922..99255fe5 100644
--- a/cli/beacon/cmd/endpoint_install.go
+++ b/cli/beacon/cmd/endpoint_install.go
@@ -104,13 +104,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.
- chooseAsymptote, err := maybeRunOnboarding(cmd)
+ connectFromOnboarding, err := maybeRunOnboarding(cmd)
if err != nil {
return err
}
- // --connect skips the destination question inside maybeRunOnboarding; either way the
- // Asymptote answer is recorded in the profile only after the connect below succeeds.
- connectAfterInstall := chooseAsymptote || endpointOpts.connect
+ // 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
result, err := lifecycle.Install(lifecycle.InstallOptions{
UserMode: endpointUserMode(),
LogPath: endpointOpts.logPath,
diff --git a/cli/beacon/cmd/endpoint_onboarding.go b/cli/beacon/cmd/endpoint_onboarding.go
index 2cbe5f97..a39944a3 100644
--- a/cli/beacon/cmd/endpoint_onboarding.go
+++ b/cli/beacon/cmd/endpoint_onboarding.go
@@ -9,6 +9,7 @@ import (
"strings"
"time"
+ "github.com/asymptote-labs/agent-beacon/cli/beacon/internal/account"
"github.com/asymptote-labs/agent-beacon/cli/beacon/internal/endpoint/asymptote"
"github.com/asymptote-labs/agent-beacon/cli/beacon/internal/onboarding"
"github.com/asymptote-labs/agent-beacon/cli/beacon/internal/version"
@@ -17,7 +18,7 @@ import (
// Environment overrides for onboarding.
const (
- // onboardingEnvEnabled set to a false-ish value skips the prompt entirely. There is
+ // onboardingEnvEnabled set to a false-ish value skips the wizard entirely. There is
// no equivalent CLI flag: this exists for unattended CI and MDM installs, not as a
// convenient way for an interactive user to decline.
onboardingEnvEnabled = "BEACON_ONBOARDING"
@@ -26,14 +27,14 @@ const (
// they just have no terminal to type it into.
onboardingEnvEmail = "BEACON_ONBOARDING_EMAIL"
onboardingEnvUsage = "BEACON_ONBOARDING_USAGE"
- // managedIngestEnvEnabled set to a false-ish value hides the Asymptote Managed row
- // from the telemetry destination question; the question itself (local or your own
- // infrastructure) is still asked. The explicit --connect flag is unaffected: the
+ // managedIngestEnvEnabled set to a false-ish value hides the Beacon Managed row
+ // from the telemetry destination question; Local remains available. Explicit --connect
+ // is unaffected: the
// variable hides an offer, it does not override an operator's request.
managedIngestEnvEnabled = "BEACON_MANAGED_INGEST"
)
-// Reasons the prompt did not run. Surfaced by `endpoint onboarding --show` so support
+// Reasons the wizard did not run. Surfaced by `endpoint onboarding --show` so support
// can tell "declined" apart from "never asked".
const (
onboardingSkipCompleted = "already_completed"
@@ -48,22 +49,21 @@ const (
var (
onboardingLoad = onboarding.Load
onboardingSave = onboarding.Save
- onboardingAsk = onboarding.Prompt
onboardingSend = onboarding.Submit
onboardingStdin io.Reader = os.Stdin
onboardingIsTTY = defaultOnboardingIsTTY
onboardingIsRoot = func() bool { return os.Geteuid() == 0 }
- onboardingProbeFn = onboarding.StartRuntimeProbe
- onboardingAskWith = onboarding.PromptWith
- onboardingAskDestination = onboarding.AskDestination
+ onboardingRunWizard = onboarding.RunWizard
+ onboardingAccountInspect = account.Inspect
+ onboardingAccountLogin = account.Login
+ onboardingAccountSave = account.Save
+ onboardingClock = time.Now
// destinationAskable reports whether the destination question makes sense here: an
// endpoint already connected to Asymptote has answered it by doing.
destinationAskable = defaultDestinationAskable
)
-// runtimeProbeBudget bounds how long submission waits on background runtime
-// discovery. The probe starts before the first question, so in practice it has
-// already finished by the time a human has typed an email.
+// runtimeProbeBudget survives for legacy unattended attribution submissions.
const runtimeProbeBudget = 2 * time.Second
// submitBudget bounds the whole submission so a wedged endpoint cannot stall an
@@ -74,9 +74,8 @@ func defaultOnboardingIsTTY() bool {
return isCharDevice(os.Stdin) && isCharDevice(os.Stdout)
}
-// maybeRunOnboarding runs the one-time signup prompt if this install should ask, and
-// reports whether the user chose Asymptote Managed as the telemetry destination, which
-// the install carries out with a connect once it has finished.
+// maybeRunOnboarding runs the one-time account and destination wizard when this
+// install is interactive. It returns true only for explicit install --connect.
//
// 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
@@ -84,15 +83,21 @@ func defaultOnboardingIsTTY() bool {
func maybeRunOnboarding(cmd *cobra.Command) (connect bool, err error) {
profile := onboardingLoad()
- // Someone who already answered is never asked again, but a submission that failed
- // on a flaky network still deserves a quiet retry. The destination question is newer
- // than the signup prompt, so a machine onboarded before it existed gets it once.
+ // Legacy pending attribution remains retryable, but new interactive installs use
+ // the signed-in account and never create another email/usage submission.
if profile.Prompted() {
resendPendingOnboarding(&profile)
- return maybeAskDestination(cmd, &profile)
+ if profile.Onboarding.Destination != "" {
+ return false, nil
+ }
+ if reason, skipped := destinationSkipReason(profile); skipped && reason != "already_connected" {
+ return false, nil
+ }
+ return runAccountOnboarding(cmd, &profile, true)
}
- // A headless rollout that supplied answers is recorded without a terminal.
+ // Preserve the explicit unattended attribution contract for MDM rollouts. It is
+ // 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
@@ -101,63 +106,94 @@ func maybeRunOnboarding(cmd *cobra.Command) (connect bool, err error) {
if _, skipped := onboardingSkipReason(profile); skipped {
return false, nil
}
+ return runAccountOnboarding(cmd, &profile, false)
+}
- // `install --connect` is already the answer to the destination question, so the
- // prompt does not ask it; the install records asymptote once the connect succeeds.
- ask := !endpointOpts.connect && destinationAskable()
-
- // Discovery shells out to every installed runtime, so start it now and collect it
- // after the questions. The latency disappears behind the user reading and typing.
- probe := onboardingProbeFn()
-
- answers, err := onboardingAskWith(onboardingStdin, cmd.OutOrStdout(), onboarding.PromptOptions{AskDestination: ask, OfferAsymptote: managedIngestEnabledByEnv()})
+func runAccountOnboarding(cmd *cobra.Command, profile *onboarding.Profile, destinationOnly bool) (bool, error) {
+ now := onboardingClock()
+ status := onboardingAccountInspect(now)
+ preset := ""
+ switch {
+ case endpointOpts.connect:
+ preset = onboarding.DestinationAsymptote
+ case !destinationAskable():
+ // A connected endpoint has already selected managed forwarding, but an
+ // upgraded installation may still need the new account sign-in.
+ preset = onboarding.DestinationAsymptote
+ }
+ options := onboarding.WizardOptions{
+ SignedIn: status.SignedIn && !status.Expired,
+ Email: status.User.Email,
+ OfferManaged: managedIngestEnabledByEnv(),
+ DestinationOnly: destinationOnly,
+ PresetDestination: preset,
+ }
+ result, err := onboardingRunWizard(onboardingStdin, cmd.OutOrStdout(), options)
if err != nil {
return false, err
}
- // Local and own-infrastructure answers are final and recorded now. Asymptote is
- // recorded by the install once the machine is actually connected
- // (recordDestinationAsymptote): if the install or the connect fails first, the record
- // stays empty and the next interactive install asks again, instead of a stored
- // answer silencing the question on a machine that never forwarded anything.
- chooseAsymptote := answers.DestinationAsked && answers.Destination == onboarding.DestinationAsymptote
- record := answers.Destination
- if chooseAsymptote {
- record = ""
- }
- completeOnboarding(cmd, &profile, answers.Email, answers.Usage, probe, record)
- return chooseAsymptote, nil
-}
-
-// maybeAskDestination asks the destination question alone, once, on an interactive
-// install of a machine that was onboarded before the question existed.
-func maybeAskDestination(cmd *cobra.Command, profile *onboarding.Profile) (bool, error) {
- if profile.Onboarding.Destination != "" || endpointOpts.connect {
- return false, nil
+ if result.NeedLogin {
+ session, err := onboardingAccountLogin(commandContext(cmd), account.LoginOptions{
+ Version: version.GetVersion(),
+ Out: cmd.OutOrStdout(),
+ Now: onboardingClock,
+ })
+ if err != nil {
+ return false, 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)
+ }
+ status = account.Status{SignedIn: true, User: session.User}
+ options.SignedIn = true
+ options.Email = status.User.Email
+ options.DestinationOnly = true
+ result, err = onboardingRunWizard(onboardingStdin, cmd.OutOrStdout(), options)
+ if err != nil {
+ return false, err
+ }
}
- if _, skipped := destinationSkipReason(*profile); skipped {
- return false, nil
+ if !result.Completed {
+ return false, onboarding.ErrWizardCancelled
}
- destination, err := onboardingAskDestination(onboardingStdin, cmd.OutOrStdout(), managedIngestEnabledByEnv())
- if err != nil {
- return false, err
+
+ recordedDestination := result.Destination
+ connectAfterInstall := endpointOpts.connect && result.Destination == onboarding.DestinationAsymptote
+ if connectAfterInstall {
+ // Explicit --connect still records managed only after device enrollment
+ // succeeds, preserving the existing retry behavior.
+ recordedDestination = ""
}
- if destination == onboarding.DestinationAsymptote {
- // Recorded by recordDestinationAsymptote once the connect has succeeded.
- return true, nil
+ 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,
+ }
+ profile.Pending = nil
+ } else {
+ profile.Onboarding.Destination = recordedDestination
+ }
+ if _, err := onboarding.EnsureInstallID(profile); err != nil {
+ return false, fmt.Errorf("create onboarding install id: %w", err)
}
- profile.Onboarding.Destination = destination
if err := onboardingSave(*profile); err != nil {
- fmt.Fprintf(cmd.ErrOrStderr(), "beacon: could not record onboarding: %v\n", err)
+ return false, fmt.Errorf("record onboarding: %w", err)
+ }
+
+ if result.Destination == onboarding.DestinationAsymptote && !connectAfterInstall {
+ fmt.Fprintln(cmd.OutOrStdout(), "Beacon Managed selected. After installation, run `beacon endpoint connect`.")
+ } else if result.Destination == onboarding.DestinationLocal {
+ fmt.Fprintln(cmd.OutOrStdout(), "Local-only telemetry selected. Open it with `beacon traces`.")
}
- return false, nil
+ return connectAfterInstall, nil
}
-// recordDestinationAsymptote stores the Asymptote answer after `endpoint install` has
-// connected the machine, whether the answer came from the question or from --connect.
-// Until then it is unrecorded on purpose, so a failed install or connect is retried by
-// asking again rather than remembered as done. A recorded local or own-infrastructure
-// answer is not overwritten: --connect on such a machine is an operator's action, not a
-// change of the owner's answer.
+// recordDestinationAsymptote stores the managed answer after explicit
+// `endpoint install --connect` succeeds. A normal wizard selection records intent
+// immediately and leaves connect as a separate command.
func recordDestinationAsymptote(cmd *cobra.Command) {
profile := onboardingLoad()
if !profile.Prompted() || profile.Onboarding.Destination != "" {
@@ -213,7 +249,7 @@ func destinationLabel(value string) string {
case onboarding.DestinationOwnInfra:
return "own infrastructure (forwarding pack)"
case onboarding.DestinationAsymptote:
- return "Asymptote Managed"
+ return "Beacon Managed"
default:
return value
}
@@ -449,15 +485,21 @@ func runEndpointOnboarding(cmd *cobra.Command, args []string) error {
}
} else {
fmt.Fprintf(out, "Onboarding: completed %s (%s)\n", status.CompletedAt, status.Outcome)
- fmt.Fprintf(out, "Email: %s\n", status.Email)
- fmt.Fprintf(out, "Usage: %s\n", status.Usage)
+ if status.Email != "" {
+ fmt.Fprintf(out, "Email: %s\n", status.Email)
+ }
+ if status.Usage != "" {
+ fmt.Fprintf(out, "Usage: %s\n", status.Usage)
+ }
}
if status.Destination != "" {
fmt.Fprintf(out, "Telemetry destination: %s\n", destinationLabel(status.Destination))
}
fmt.Fprintf(out, "Install ID: %s\n", status.InstallID)
fmt.Fprintf(out, "Profile: %s\n", status.ProfilePath)
- fmt.Fprintf(out, "Endpoint: %s\n", status.Endpoint)
+ if status.Outcome != onboarding.OutcomeAuthenticated {
+ fmt.Fprintf(out, "Legacy signup endpoint: %s\n", status.Endpoint)
+ }
if status.Pending {
fmt.Fprintln(out, "A signup is queued for resend. Retry with: beacon endpoint onboarding --resend")
}
diff --git a/cli/beacon/cmd/endpoint_onboarding_test.go b/cli/beacon/cmd/endpoint_onboarding_test.go
index 8b7a9e9b..f4e302d3 100644
--- a/cli/beacon/cmd/endpoint_onboarding_test.go
+++ b/cli/beacon/cmd/endpoint_onboarding_test.go
@@ -8,7 +8,9 @@ import (
"os"
"strings"
"testing"
+ "time"
+ "github.com/asymptote-labs/agent-beacon/cli/beacon/internal/account"
"github.com/asymptote-labs/agent-beacon/cli/beacon/internal/onboarding"
"github.com/spf13/cobra"
)
@@ -16,19 +18,18 @@ import (
// onboardingHarness isolates the package-level state the onboarding gate reads, so a
// test can describe exactly one situation without inheriting another's leftovers.
type onboardingHarness struct {
- t *testing.T
- cmd *cobra.Command
- stdout *bytes.Buffer
- stderr *bytes.Buffer
- asked bool
- sent []onboarding.Submission
- saved []onboarding.Profile
- loaded onboarding.Profile
- answers onboarding.Answers
- askErr error
- outcome string
- sendErr error
- probeRuns int
+ t *testing.T
+ cmd *cobra.Command
+ stdout *bytes.Buffer
+ stderr *bytes.Buffer
+ asked bool
+ sent []onboarding.Submission
+ saved []onboarding.Profile
+ loaded onboarding.Profile
+ answers onboarding.Answers
+ askErr error
+ outcome string
+ sendErr error
// offered records the PromptOptions the prompt was invoked with; askable and
// standaloneAnswer drive the destination question.
offered []onboarding.PromptOptions
@@ -36,6 +37,9 @@ type onboardingHarness struct {
standaloneAsked bool
standaloneOffered bool
standaloneAnswer string
+ accountStatus account.Status
+ loginRuns int
+ loginErr error
}
func newOnboardingHarness(t *testing.T) *onboardingHarness {
@@ -47,6 +51,11 @@ func newOnboardingHarness(t *testing.T) *onboardingHarness {
stderr: &bytes.Buffer{},
answers: onboarding.Answers{Email: "[email protected]", Usage: onboarding.UsageWork},
outcome: onboarding.OutcomeSubmitted,
+ askable: true,
+ accountStatus: account.Status{
+ SignedIn: true,
+ User: account.User{ID: "usr_1", Email: "[email protected]"},
+ },
}
h.cmd = &cobra.Command{}
h.cmd.SetOut(h.stdout)
@@ -69,9 +78,12 @@ func newOnboardingHarness(t *testing.T) *onboardingHarness {
t.Setenv(onboardingEnvUsage, "")
t.Setenv("HOME", t.TempDir())
- prevLoad, prevSave, prevAsk, prevSend := onboardingLoad, onboardingSave, onboardingAskWith, onboardingSend
- prevTTY, prevRoot, prevProbe := onboardingIsTTY, onboardingIsRoot, onboardingProbeFn
- prevStandalone, prevAskable := onboardingAskDestination, destinationAskable
+ prevLoad, prevSave, prevSend := onboardingLoad, onboardingSave, onboardingSend
+ prevTTY, prevRoot := onboardingIsTTY, onboardingIsRoot
+ prevAskable := destinationAskable
+ prevWizard := onboardingRunWizard
+ prevAccountInspect, prevAccountLogin, prevAccountSave := onboardingAccountInspect, onboardingAccountLogin, onboardingAccountSave
+ prevClock := onboardingClock
t.Setenv(managedIngestEnvEnabled, "")
onboardingLoad = func() onboarding.Profile { return h.loaded }
@@ -79,33 +91,64 @@ func newOnboardingHarness(t *testing.T) *onboardingHarness {
h.saved = append(h.saved, p)
return nil
}
- onboardingAskWith = func(_ io.Reader, _ io.Writer, opts onboarding.PromptOptions) (onboarding.Answers, error) {
- h.asked = true
- h.offered = append(h.offered, opts)
- return h.answers, h.askErr
- }
- onboardingAskDestination = func(_ io.Reader, _ io.Writer, offerAsymptote bool) (string, error) {
- h.standaloneAsked = true
- h.standaloneOffered = offerAsymptote
- return h.standaloneAnswer, nil
- }
destinationAskable = func() bool { return h.askable }
+ onboardingRunWizard = func(_ io.Reader, _ io.Writer, opts onboarding.WizardOptions) (onboarding.WizardResult, error) {
+ if h.askErr != nil {
+ return onboarding.WizardResult{}, h.askErr
+ }
+ destination := opts.PresetDestination
+ if opts.DestinationOnly {
+ h.standaloneAsked = true
+ h.standaloneOffered = opts.OfferManaged
+ if destination == "" {
+ destination = h.standaloneAnswer
+ }
+ } else {
+ h.asked = true
+ h.offered = append(h.offered, onboarding.PromptOptions{
+ AskDestination: destinationAskable() && !endpointOpts.connect,
+ OfferAsymptote: opts.OfferManaged,
+ })
+ if destination == "" && h.answers.DestinationAsked {
+ destination = h.answers.Destination
+ }
+ }
+ if !opts.SignedIn {
+ return onboarding.WizardResult{NeedLogin: true}, nil
+ }
+ if destination == "" {
+ destination = onboarding.DestinationLocal
+ }
+ return onboarding.WizardResult{Completed: true, Destination: destination}, nil
+ }
+ onboardingAccountInspect = func(time.Time) account.Status { return h.accountStatus }
+ onboardingAccountLogin = func(context.Context, account.LoginOptions) (*account.Session, error) {
+ h.loginRuns++
+ if h.loginErr != nil {
+ return nil, h.loginErr
+ }
+ return &account.Session{
+ BaseURL: account.DefaultBaseURL,
+ AccessToken: "token",
+ User: account.User{ID: "usr_1", Email: "[email protected]"},
+ }, nil
+ }
+ onboardingAccountSave = func(account.Session) error { return nil }
+ onboardingClock = func() time.Time { return time.Date(2026, 9, 21, 8, 0, 0, 0, time.UTC) }
onboardingSend = func(_ context.Context, s onboarding.Submission) (string, error) {
h.sent = append(h.sent, s)
return h.outcome, h.sendErr
}
onboardingIsTTY = func() bool { return true }
onboardingIsRoot = func() bool { return false }
- onboardingProbeFn = func() *onboarding.RuntimeProbe {
- h.probeRuns++
- return nil
- }
-
t.Cleanup(func() {
endpointOpts = prevOpts
- onboardingLoad, onboardingSave, onboardingAskWith, onboardingSend = prevLoad, prevSave, prevAsk, prevSend
- onboardingIsTTY, onboardingIsRoot, onboardingProbeFn = prevTTY, prevRoot, prevProbe
- onboardingAskDestination, destinationAskable = prevStandalone, prevAskable
+ onboardingLoad, onboardingSave, onboardingSend = prevLoad, prevSave, prevSend
+ onboardingIsTTY, onboardingIsRoot = prevTTY, prevRoot
+ destinationAskable = prevAskable
+ onboardingRunWizard = prevWizard
+ onboardingAccountInspect, onboardingAccountLogin, onboardingAccountSave = prevAccountInspect, prevAccountLogin, prevAccountSave
+ onboardingClock = prevClock
})
return h
}
@@ -117,20 +160,19 @@ func TestMaybeRunOnboardingPromptsOnInteractiveInstall(t *testing.T) {
t.Fatalf("maybeRunOnboarding returned error: %v", err)
}
if !h.asked {
- t.Fatalf("expected the prompt to run on an interactive per-user install")
- }
- if len(h.sent) != 1 {
- t.Fatalf("submissions = %d, want 1", len(h.sent))
- }
- if h.sent[0].Email != "[email protected]" || h.sent[0].Usage != onboarding.UsageWork {
- t.Fatalf("submission = %+v, want the prompt answers", h.sent[0])
+ t.Fatalf("expected the wizard to run on an interactive per-user install")
}
- if h.sent[0].InstallMode != "user" {
- t.Fatalf("install_mode = %q, want user", h.sent[0].InstallMode)
+ if len(h.sent) != 0 {
+ t.Fatalf("interactive account onboarding sent %d legacy submissions", len(h.sent))
}
if len(h.saved) != 1 || !h.saved[0].Prompted() {
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.DestinationLocal {
+ t.Fatalf("saved account onboarding = %+v", h.saved[0].Onboarding)
+ }
if h.saved[0].InstallID == "" {
t.Fatalf("saved profile has no install ID")
}
@@ -147,7 +189,7 @@ func TestMaybeRunOnboardingStaysSilentWhenGated(t *testing.T) {
{
name: "already completed",
arrange: func(_ *testing.T, h *onboardingHarness) {
- h.loaded = onboarding.Profile{Onboarding: onboarding.Onboarding{CompletedAt: "2026-08-07T00:00:00Z"}}
+ h.loaded = onboarding.Profile{Onboarding: onboarding.Onboarding{CompletedAt: "2026-08-07T00:00:00Z", Destination: onboarding.DestinationLocal}}
},
wantReason: onboardingSkipCompleted,
},
@@ -234,44 +276,35 @@ func TestMaybeRunOnboardingPropagatesPromptFailure(t *testing.T) {
}
}
-// The user answered; the network did not cooperate. That is our problem, not theirs.
-func TestMaybeRunOnboardingSurvivesSubmissionFailure(t *testing.T) {
+func TestInteractiveOnboardingSignsInWithoutLegacySubmission(t *testing.T) {
h := newOnboardingHarness(t)
- h.outcome = onboarding.OutcomePending
- h.sendErr = errors.New("connection refused")
+ h.accountStatus = account.Status{}
if _, err := maybeRunOnboarding(h.cmd); err != nil {
t.Fatalf("maybeRunOnboarding returned error: %v", err)
}
- if len(h.saved) != 1 {
- t.Fatalf("saved = %d profiles, want 1", len(h.saved))
- }
- saved := h.saved[0]
- if !saved.Prompted() {
- t.Fatalf("profile is not marked completed, so the user would be asked again")
+ if h.loginRuns != 1 {
+ t.Fatalf("login runs = %d, want 1", h.loginRuns)
}
- if saved.Onboarding.Outcome != onboarding.OutcomePending {
- t.Fatalf("outcome = %q, want %q", saved.Onboarding.Outcome, onboarding.OutcomePending)
+ if len(h.sent) != 0 {
+ t.Fatalf("interactive onboarding sent legacy payloads: %+v", h.sent)
}
- if saved.Pending == nil {
- t.Fatalf("pending payload was not kept, so the signup can never be resent")
+ if len(h.saved) != 1 || h.saved[0].Onboarding.Outcome != onboarding.OutcomeAuthenticated {
+ t.Fatalf("saved = %+v", h.saved)
}
}
-// A refusal is terminal, and the address should not linger on disk afterwards.
-func TestMaybeRunOnboardingDropsPayloadWhenRejected(t *testing.T) {
+func TestInteractiveOnboardingStopsWhenRequiredLoginFails(t *testing.T) {
h := newOnboardingHarness(t)
- h.outcome = onboarding.OutcomeRejected
- h.sendErr = errors.New("signup endpoint returned 429 Too Many Requests")
+ h.accountStatus = account.Status{}
+ h.loginErr = errors.New("authentication service unavailable")
- if _, err := maybeRunOnboarding(h.cmd); err != nil {
- t.Fatalf("maybeRunOnboarding returned error: %v", err)
- }
- if h.saved[0].Pending != nil {
- t.Fatalf("kept a payload for a terminal rejection")
+ _, err := maybeRunOnboarding(h.cmd)
+ if err == nil || !strings.Contains(err.Error(), "sign-in is required") {
+ t.Fatalf("error = %v", err)
}
- if !strings.Contains(h.stderr.String(), "continuing") {
- t.Fatalf("stderr = %q, want a note that the install continues", h.stderr.String())
+ if len(h.saved) != 0 || len(h.sent) != 0 {
+ t.Fatalf("failed login persisted onboarding: saved=%+v sent=%+v", h.saved, h.sent)
}
}
@@ -280,7 +313,7 @@ func TestMaybeRunOnboardingResendsPendingSubmission(t *testing.T) {
pending := onboarding.Submission{InstallID: "abc123", Email: "[email protected]"}
h.loaded = onboarding.Profile{
InstallID: "abc123",
- Onboarding: onboarding.Onboarding{CompletedAt: "2026-08-07T00:00:00Z", Outcome: onboarding.OutcomePending},
+ Onboarding: onboarding.Onboarding{CompletedAt: "2026-08-07T00:00:00Z", Outcome: onboarding.OutcomePending, Destination: onboarding.DestinationLocal},
Pending: &pending,
}
@@ -303,7 +336,7 @@ func TestMaybeRunOnboardingKeepsPendingWhenResendFails(t *testing.T) {
h.outcome = onboarding.OutcomePending
pending := onboarding.Submission{InstallID: "abc123"}
h.loaded = onboarding.Profile{
- Onboarding: onboarding.Onboarding{CompletedAt: "2026-08-07T00:00:00Z", Outcome: onboarding.OutcomePending},
+ Onboarding: onboarding.Onboarding{CompletedAt: "2026-08-07T00:00:00Z", Outcome: onboarding.OutcomePending, Destination: onboarding.DestinationLocal},
Pending: &pending,
}
@@ -399,6 +432,33 @@ func TestEndpointOnboardingShowsRecord(t *testing.T) {
}
}
+func TestEndpointOnboardingShowsAuthenticatedRecordWithoutLegacyFields(t *testing.T) {
+ h := newOnboardingHarness(t)
+ h.loaded = onboarding.Profile{
+ InstallID: "abc123",
+ Onboarding: onboarding.Onboarding{
+ CompletedAt: "2026-09-21T08:00:00Z",
+ Outcome: onboarding.OutcomeAuthenticated,
+ Email: "[email protected]",
+ Destination: onboarding.DestinationLocal,
+ },
+ }
+ if err := runEndpointOnboarding(h.cmd, nil); err != nil {
+ t.Fatal(err)
+ }
+ out := h.stdout.String()
+ for _, want := range []string{"authenticated", "[email protected]", "local only"} {
+ if !strings.Contains(out, want) {
+ t.Fatalf("output missing %q:\n%s", want, out)
+ }
+ }
+ for _, unwanted := range []string{"Usage:", "Legacy signup endpoint:"} {
+ if strings.Contains(out, unwanted) {
+ t.Fatalf("authenticated output contains %q:\n%s", unwanted, out)
+ }
+ }
+}
+
func TestEndpointOnboardingResetRemovesProfile(t *testing.T) {
h := newOnboardingHarness(t)
endpointOpts.onboardingReset = true
@@ -486,7 +546,7 @@ func TestRetryPendingOnboardingResendsWithoutPrompting(t *testing.T) {
pending := onboarding.Submission{InstallID: "abc123", Email: "[email protected]"}
h.loaded = onboarding.Profile{
InstallID: "abc123",
- Onboarding: onboarding.Onboarding{CompletedAt: "2026-08-07T00:00:00Z", Outcome: onboarding.OutcomePending},
+ Onboarding: onboarding.Onboarding{CompletedAt: "2026-08-07T00:00:00Z", Outcome: onboarding.OutcomePending, Destination: onboarding.DestinationLocal},
Pending: &pending,
}
@@ -524,7 +584,7 @@ func TestRetryPendingOnboardingIsSilentWithNothingQueued(t *testing.T) {
}
}
-func TestMaybeRunOnboardingAsksDestinationOnlyWhenAskable(t *testing.T) {
+func TestMaybeRunOnboardingRecordsLocalOrManagedIntent(t *testing.T) {
h := newOnboardingHarness(t)
h.askable = false
if connect, err := maybeRunOnboarding(h.cmd); err != nil || connect {
@@ -533,8 +593,8 @@ func TestMaybeRunOnboardingAsksDestinationOnlyWhenAskable(t *testing.T) {
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)
}
- if h.saved[len(h.saved)-1].Onboarding.Destination != "" {
- t.Fatal("a question that was not asked must not be recorded")
+ if got := h.saved[len(h.saved)-1].Onboarding.Destination; got != onboarding.DestinationAsymptote {
+ t.Fatalf("connected endpoint destination = %q, want managed", got)
}
h = newOnboardingHarness(t)
@@ -542,27 +602,25 @@ func TestMaybeRunOnboardingAsksDestinationOnlyWhenAskable(t *testing.T) {
h.answers.DestinationAsked = true
h.answers.Destination = onboarding.DestinationAsymptote
connect, err := maybeRunOnboarding(h.cmd)
- if err != nil || !connect {
- t.Fatalf("the Asymptote answer should request a connect: connect=%t err=%v", connect, err)
+ if err != nil || connect {
+ t.Fatalf("managed intent should leave connect as a separate step: connect=%t err=%v", connect, err)
}
if !h.offered[0].AskDestination || !h.offered[0].OfferAsymptote {
- t.Fatalf("prompt should have been asked to offer all three destinations: %+v", h.offered[0])
+ t.Fatalf("wizard should offer local and managed destinations: %+v", h.offered[0])
}
- if got := h.saved[len(h.saved)-1].Onboarding.Destination; got != "" {
- t.Fatalf("asymptote is recorded only once the install has connected the machine, got %q", got)
+ if got := h.saved[len(h.saved)-1].Onboarding.Destination; got != onboarding.DestinationAsymptote {
+ t.Fatalf("managed intent was not recorded, got %q", got)
}
- for _, answer := range []string{onboarding.DestinationLocal, onboarding.DestinationOwnInfra} {
- h = newOnboardingHarness(t)
- h.askable = true
- h.answers.DestinationAsked = true
- h.answers.Destination = answer
- if connect, _ := maybeRunOnboarding(h.cmd); connect {
- t.Fatalf("%s must not connect", answer)
- }
- if got := h.saved[len(h.saved)-1].Onboarding.Destination; got != answer {
- t.Fatalf("recorded destination = %q, want %q", got, answer)
- }
+ h = newOnboardingHarness(t)
+ h.askable = true
+ h.answers.DestinationAsked = true
+ h.answers.Destination = onboarding.DestinationLocal
+ if connect, _ := maybeRunOnboarding(h.cmd); connect {
+ t.Fatal("local selection must not connect")
+ }
+ if got := h.saved[len(h.saved)-1].Onboarding.Destination; got != onboarding.DestinationLocal {
+ t.Fatalf("recorded destination = %q, want local", got)
}
}
@@ -584,10 +642,13 @@ func TestDestinationQuestionHidesAsymptoteWhenOptedOut(t *testing.T) {
h.askable = true
t.Setenv(managedIngestEnvEnabled, "0")
h.loaded = onboarding.Profile{InstallID: "abc", Onboarding: onboarding.Onboarding{CompletedAt: "2026-08-01T00:00:00Z"}}
- h.standaloneAnswer = onboarding.DestinationOwnInfra
+ h.standaloneAnswer = onboarding.DestinationLocal
if _, err := maybeRunOnboarding(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 {
+ t.Fatalf("destination = %q, want local", got)
+ }
}
func TestDestinationAskedOnceToPreviouslyOnboardedMachine(t *testing.T) {
@@ -596,7 +657,7 @@ func TestDestinationAskedOnceToPreviouslyOnboardedMachine(t *testing.T) {
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 {
+ if err != nil || connect {
t.Fatalf("connect=%t err=%v", connect, err)
}
if h.asked {
@@ -605,22 +666,20 @@ 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) != 0 {
- t.Fatalf("asymptote must not be recorded before the connect succeeds: %+v", h.saved)
+ 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)
}
- // Local and own infrastructure are recorded at once.
- for _, answer := range []string{onboarding.DestinationLocal, onboarding.DestinationOwnInfra} {
- h = newOnboardingHarness(t)
- h.askable = true
- h.loaded = onboarding.Profile{InstallID: "abc", Onboarding: onboarding.Onboarding{CompletedAt: "2026-08-01T00:00:00Z"}}
- h.standaloneAnswer = answer
- if connect, _ := maybeRunOnboarding(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 != answer {
- t.Fatalf("recorded destination = %q, want %q", got, answer)
- }
+ // Local is recorded at once.
+ h = newOnboardingHarness(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 {
+ t.Fatalf("connect=%t asked=%t", connect, h.standaloneAsked)
+ }
+ if got := h.saved[len(h.saved)-1].Onboarding.Destination; got != onboarding.DestinationLocal {
+ t.Fatalf("recorded destination = %q, want local", got)
}
// Once recorded, it is never asked again.
@@ -646,67 +705,38 @@ func TestDestinationAskedOnceToPreviouslyOnboardedMachine(t *testing.T) {
if connect, _ := maybeRunOnboarding(h.cmd); connect || h.standaloneAsked {
t.Fatal("CI never sees the question")
}
- // A connected endpoint has answered by doing.
+ // An upgraded connected endpoint signs in and records managed without asking
+ // the operator to choose a conflicting destination.
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 {
- t.Fatal("a connected endpoint is not asked")
+ if connect, _ := maybeRunOnboarding(h.cmd); connect || !h.standaloneAsked {
+ t.Fatal("a connected endpoint should complete the account migration")
+ }
+ if got := h.saved[len(h.saved)-1].Onboarding.Destination; got != onboarding.DestinationAsymptote {
+ t.Fatalf("connected endpoint destination = %q", got)
}
}
-// An Asymptote answer whose install or connect failed must be asked again, not remembered
-// as done: the record is written only by recordDestinationAsymptote, after the connect.
-func TestAsymptoteDestinationIsRecordedAfterConnect(t *testing.T) {
+func TestManagedDestinationIsRecordedAsIntent(t *testing.T) {
h := newOnboardingHarness(t)
h.askable = true
h.answers.DestinationAsked = true
h.answers.Destination = onboarding.DestinationAsymptote
- if connect, err := maybeRunOnboarding(h.cmd); err != nil || !connect {
+ if connect, err := maybeRunOnboarding(h.cmd); err != nil || connect {
t.Fatalf("connect=%t err=%v", connect, err)
}
afterPrompt := h.saved[len(h.saved)-1]
- if afterPrompt.Onboarding.Destination != "" {
- t.Fatalf("recorded before connect: %q", afterPrompt.Onboarding.Destination)
+ if afterPrompt.Onboarding.Destination != onboarding.DestinationAsymptote {
+ t.Fatalf("managed intent = %q", afterPrompt.Onboarding.Destination)
+ }
+ if !strings.Contains(h.stdout.String(), "beacon endpoint connect") {
+ t.Fatalf("managed next step missing: %s", h.stdout.String())
}
-
- // The install failed before connecting: the next interactive install asks again.
h2 := newOnboardingHarness(t)
- h2.askable = true
h2.loaded = afterPrompt
- h2.standaloneAnswer = onboarding.DestinationAsymptote
- if connect, err := maybeRunOnboarding(h2.cmd); err != nil || !connect || !h2.standaloneAsked || h2.asked {
- t.Fatalf("connect=%t err=%v standaloneAsked=%t signupAsked=%t", connect, err, h2.standaloneAsked, h2.asked)
- }
-
- // The install connected: the answer is recorded and the question retires.
- h3 := newOnboardingHarness(t)
- h3.askable = true
- h3.loaded = afterPrompt
- recordDestinationAsymptote(h3.cmd)
- if got := h3.saved[len(h3.saved)-1].Onboarding.Destination; got != onboarding.DestinationAsymptote {
- t.Fatalf("recorded destination = %q", got)
- }
- h4 := newOnboardingHarness(t)
- h4.askable = true
- h4.loaded = h3.saved[len(h3.saved)-1]
- if connect, _ := maybeRunOnboarding(h4.cmd); connect || h4.standaloneAsked {
- t.Fatalf("a recorded destination must not be asked again: connect=%t asked=%t", connect, h4.standaloneAsked)
- }
-
- // Never written for a machine that was not onboarded (root, CI, --connect without a prompt).
- h5 := newOnboardingHarness(t)
- recordDestinationAsymptote(h5.cmd)
- if len(h5.saved) != 0 {
- t.Fatalf("no profile should be written without a completed onboarding: %+v", h5.saved)
- }
-
- // A recorded local answer stays local even when an operator connects with --connect.
- h6 := newOnboardingHarness(t)
- h6.loaded = onboarding.Profile{InstallID: "abc", Onboarding: onboarding.Onboarding{CompletedAt: "2026-08-01T00:00:00Z", Destination: onboarding.DestinationLocal}}
- recordDestinationAsymptote(h6.cmd)
- if len(h6.saved) != 0 {
- t.Fatalf("an owner's answer must not be rewritten: %+v", h6.saved)
+ 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)
}
}
@@ -718,7 +748,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 := maybeRunOnboarding(h.cmd); err != nil || !connect {
t.Fatalf("connect=%t err=%v", connect, err)
}
if len(h.offered) != 1 || h.offered[0].AskDestination {
@@ -731,7 +761,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 := maybeRunOnboarding(h.cmd); err != nil || !connect || !h.standaloneAsked {
t.Fatalf("connect=%t err=%v asked=%t", connect, err, h.standaloneAsked)
}
@@ -752,7 +782,7 @@ func TestEndpointOnboardingShowsDestination(t *testing.T) {
for value, want := range map[string]string{
onboarding.DestinationLocal: "Telemetry destination: local only",
onboarding.DestinationOwnInfra: "Telemetry destination: own infrastructure",
- onboarding.DestinationAsymptote: "Telemetry destination: Asymptote Managed",
+ onboarding.DestinationAsymptote: "Telemetry destination: Beacon Managed",
} {
h := newOnboardingHarness(t)
h.loaded = onboarding.Profile{InstallID: "abc", Onboarding: onboarding.Onboarding{CompletedAt: "2026-08-01T00:00:00Z", Outcome: onboarding.OutcomeSubmitted, Email: "[email protected]", Usage: onboarding.UsageWork, Destination: value}}
diff --git a/cli/beacon/internal/onboarding/profile.go b/cli/beacon/internal/onboarding/profile.go
index 93a89164..96160874 100644
--- a/cli/beacon/internal/onboarding/profile.go
+++ b/cli/beacon/internal/onboarding/profile.go
@@ -1,6 +1,5 @@
-// Package onboarding implements Beacon's one-time, install-time account signal:
-// a prompt for the operator's email and how they are using Beacon, submitted once
-// to an Asymptote-run endpoint.
+// Package onboarding implements Beacon's one-time interactive install wizard and
+// retains the legacy attribution record used by unattended deployments.
//
// Everything here is best-effort. Onboarding never fails an install, never runs
// outside an interactive terminal, and never runs twice on the same machine.
@@ -40,6 +39,9 @@ const (
OutcomeRejected = "rejected"
// OutcomeSkipped means the user opted out through a documented escape hatch.
OutcomeSkipped = "skipped"
+ // OutcomeAuthenticated means the interactive wizard used the signed-in Beacon
+ // account instead of the legacy email/usage submission.
+ OutcomeAuthenticated = "authenticated"
)
// Profile is the persisted per-machine Beacon profile.
@@ -57,10 +59,9 @@ type Onboarding struct {
Email string `json:"email,omitempty"`
Usage string `json:"usage,omitempty"`
BeaconVersion string `json:"beacon_version,omitempty"`
- // Destination records where the user chose to send this machine's telemetry:
- // local, own_infra or asymptote. Empty means the question has not been answered on
- // this machine, so a later interactive install may ask once. asymptote is written
- // only after the connect succeeds, so a failed connect is asked again.
+ // Destination records where the user chose to send this machine's telemetry.
+ // New interactive installs choose local or asymptote; own_infra remains valid for
+ // profiles written by older versions and unattended/admin-managed deployments.
Destination string `json:"destination,omitempty"`
}
diff --git a/cli/beacon/internal/onboarding/wizard.go b/cli/beacon/internal/onboarding/wizard.go
new file mode 100644
index 00000000..6c842b0f
--- /dev/null
+++ b/cli/beacon/internal/onboarding/wizard.go
@@ -0,0 +1,225 @@
+package onboarding
+
+import (
+ "errors"
+ "io"
+ "strings"
+
+ tea "github.com/charmbracelet/bubbletea"
+ "github.com/charmbracelet/lipgloss"
+)
+
+var ErrWizardCancelled = errors.New("onboarding cancelled")
+
+type WizardOptions struct {
+ SignedIn bool
+ Email string
+ OfferManaged bool
+ DestinationOnly bool
+ PresetDestination string
+}
+
+type WizardResult struct {
+ NeedLogin bool
+ Completed bool
+ Destination string
+}
+
+type wizardScreen int
+
+const (
+ welcomeScreen wizardScreen = iota
+ signInScreen
+ destinationScreen
+ managedDisclosureScreen
+ confirmScreen
+)
+
+type wizardModel struct {
+ options WizardOptions
+ result WizardResult
+ screen wizardScreen
+ selected int
+ width int
+ height int
+}
+
+var (
+ wizardAccent = lipgloss.NewStyle().Foreground(lipgloss.Color("99")).Bold(true)
+ wizardDim = lipgloss.NewStyle().Foreground(lipgloss.Color("245"))
+ wizardChoice = lipgloss.NewStyle().Foreground(lipgloss.Color("15")).Background(lipgloss.Color("237")).Bold(true)
+ wizardWarn = lipgloss.NewStyle().Foreground(lipgloss.Color("214")).Bold(true)
+)
+
+func newWizardModel(options WizardOptions) wizardModel {
+ screen := welcomeScreen
+ result := WizardResult{Destination: options.PresetDestination}
+ if options.DestinationOnly {
+ switch {
+ case !options.SignedIn:
+ screen = signInScreen
+ case options.PresetDestination == DestinationAsymptote:
+ screen = managedDisclosureScreen
+ case options.PresetDestination != "":
+ screen = confirmScreen
+ default:
+ screen = destinationScreen
+ }
+ }
+ return wizardModel{options: options, result: result, screen: screen}
+}
+
+func RunWizard(in io.Reader, out io.Writer, options WizardOptions) (WizardResult, error) {
+ model := newWizardModel(options)
+ program := tea.NewProgram(model, tea.WithAltScreen(), tea.WithInput(in), tea.WithOutput(out))
+ final, err := program.Run()
+ if err != nil {
+ return WizardResult{}, err
+ }
+ result := final.(wizardModel).result
+ if !result.NeedLogin && !result.Completed {
+ return WizardResult{}, ErrWizardCancelled
+ }
+ return result, nil
+}
+
+func (m wizardModel) Init() tea.Cmd {
+ return nil
+}
+
+func (m wizardModel) Update(message tea.Msg) (tea.Model, tea.Cmd) {
+ switch msg := message.(type) {
+ case tea.WindowSizeMsg:
+ m.width, m.height = msg.Width, msg.Height
+ case tea.KeyMsg:
+ switch msg.String() {
+ case "ctrl+c", "q", "esc":
+ return m, tea.Quit
+ case "up", "k":
+ if m.screen == destinationScreen {
+ m.selected = (m.selected - 1 + len(m.destinations())) % len(m.destinations())
+ }
+ case "down", "j":
+ if m.screen == destinationScreen {
+ m.selected = (m.selected + 1) % len(m.destinations())
+ }
+ case "enter":
+ return m.advance()
+ }
+ }
+ return m, nil
+}
+
+func (m wizardModel) advance() (tea.Model, tea.Cmd) {
+ switch m.screen {
+ case welcomeScreen:
+ switch {
+ case !m.options.SignedIn:
+ m.screen = signInScreen
+ case m.options.PresetDestination == DestinationAsymptote:
+ m.screen = managedDisclosureScreen
+ case m.options.PresetDestination != "":
+ m.screen = confirmScreen
+ default:
+ m.screen = destinationScreen
+ }
+ case signInScreen:
+ m.result.NeedLogin = true
+ return m, tea.Quit
+ case destinationScreen:
+ m.result.Destination = m.destinations()[m.selected]
+ if m.result.Destination == DestinationAsymptote {
+ m.screen = managedDisclosureScreen
+ } else {
+ m.screen = confirmScreen
+ }
+ case managedDisclosureScreen:
+ m.screen = confirmScreen
+ case confirmScreen:
+ m.result.Completed = true
+ return m, tea.Quit
+ }
+ return m, nil
+}
+
+func (m wizardModel) destinations() []string {
+ destinations := []string{DestinationLocal}
+ if m.options.OfferManaged {
+ destinations = append(destinations, DestinationAsymptote)
+ }
+ return destinations
+}
+
+func (m wizardModel) View() string {
+ width := m.width
+ if width <= 0 {
+ width = 80
+ }
+ var title, body string
+ switch m.screen {
+ case welcomeScreen:
+ title = "Welcome to Beacon"
+ body = "One local timeline for every AI agent.\n\nThis interactive setup signs you in, then asks whether telemetry should stay local or be forwarded to Beacon Managed."
+ if m.options.SignedIn {
+ body += "\n\n" + wizardDim.Render("Signed in as "+m.options.Email)
+ }
+ case signInScreen:
+ title = "Sign in to continue"
+ body = "Beacon will open beacon.sh in your browser using a secure PKCE flow.\n\nSigning in does not send telemetry, register a managed endpoint, or enable forwarding."
+ case destinationScreen:
+ title = "Where should this machine's telemetry go?"
+ var rows []string
+ for index, destination := range m.destinations() {
+ label, detail := destinationCopy(destination)
+ prefix := " "
+ line := prefix + label
+ if index == m.selected {
+ line = wizardChoice.Render(" ❯ " + label)
+ }
+ rows = append(rows, line, wizardDim.Render(" "+detail))
+ }
+ 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, Vector sends new runtime and inventory events to beacon.sh over HTTPS. Existing local history is not uploaded."
+ case confirmScreen:
+ title = "Ready to install"
+ label, _ := destinationCopy(m.result.Destination)
+ body = "Account: " + m.options.Email + "\nDestination: " + label
+ if m.result.Destination == DestinationAsymptote {
+ body += "\n\nNext step after install: beacon endpoint connect"
+ } else {
+ body += "\n\nYour telemetry stays on this machine."
+ }
+ }
+
+ contentWidth := min(76, max(30, width-8))
+ 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))
+ return lipgloss.NewStyle().Padding(1, 3).Render(card)
+}
+
+func destinationCopy(destination string) (string, string) {
+ switch destination {
+ case DestinationAsymptote:
+ return "Beacon Managed", "Keep local JSONL and optionally forward new events to beacon.sh."
+ default:
+ return "Local only", "Nothing is sent anywhere. Browse with `beacon traces` or the local dashboard."
+ }
+}
+
+func wizardHint(screen wizardScreen) string {
+ switch screen {
+ case destinationScreen:
+ return "↑/↓ choose · enter continue · esc cancel"
+ case signInScreen:
+ return "enter open beacon.sh · esc cancel"
+ case confirmScreen:
+ return "enter install · esc cancel"
+ default:
+ return "enter continue · esc cancel"
+ }
+}
diff --git a/cli/beacon/internal/onboarding/wizard_test.go b/cli/beacon/internal/onboarding/wizard_test.go
new file mode 100644
index 00000000..d4cf52b7
--- /dev/null
+++ b/cli/beacon/internal/onboarding/wizard_test.go
@@ -0,0 +1,119 @@
+package onboarding
+
+import (
+ "strings"
+ "testing"
+
+ tea "github.com/charmbracelet/bubbletea"
+)
+
+func wizardKey(value string) tea.KeyMsg {
+ switch value {
+ case "enter":
+ return tea.KeyMsg{Type: tea.KeyEnter}
+ case "esc":
+ return tea.KeyMsg{Type: tea.KeyEsc}
+ default:
+ return tea.KeyMsg{Type: tea.KeyRunes, Runes: []rune(value)}
+ }
+}
+
+func advanceWizard(t *testing.T, model wizardModel, key string) (wizardModel, tea.Cmd) {
+ t.Helper()
+ next, command := model.Update(wizardKey(key))
+ return next.(wizardModel), command
+}
+
+func TestWizardRequestsLoginBeforeDestination(t *testing.T) {
+ model := newWizardModel(WizardOptions{OfferManaged: true})
+ model.width, model.height = 100, 30
+ model, _ = advanceWizard(t, model, "enter")
+ if model.screen != signInScreen {
+ t.Fatalf("screen = %v, want sign in", model.screen)
+ }
+ if view := model.View(); !strings.Contains(view, "does not send telemetry") {
+ t.Fatalf("sign-in disclosure missing:\n%s", view)
+ }
+ model, command := advanceWizard(t, model, "enter")
+ if command == nil || !model.result.NeedLogin || model.result.Completed {
+ t.Fatalf("result = %#v command=%v", model.result, command != nil)
+ }
+}
+
+func TestSignedInWizardDefaultsToLocalAndCompletes(t *testing.T) {
+ model := newWizardModel(WizardOptions{
+ SignedIn: true,
+ Email: "[email protected]",
+ OfferManaged: true,
+ })
+ model.width, model.height = 100, 30
+ model, _ = advanceWizard(t, model, "enter")
+ if model.screen != destinationScreen {
+ t.Fatalf("screen = %v, want destination", model.screen)
+ }
+ model, _ = advanceWizard(t, model, "enter")
+ if model.screen != confirmScreen || model.result.Destination != DestinationLocal {
+ t.Fatalf("local selection = screen %v result %#v", model.screen, model.result)
+ }
+ if view := model.View(); !strings.Contains(view, "telemetry stays on this machine") {
+ t.Fatalf("local confirmation missing:\n%s", view)
+ }
+ model, command := advanceWizard(t, model, "enter")
+ if command == nil || !model.result.Completed {
+ t.Fatalf("completion = %#v command=%v", model.result, command != nil)
+ }
+}
+
+func TestManagedWizardRequiresDisclosureConfirmation(t *testing.T) {
+ model := newWizardModel(WizardOptions{
+ SignedIn: true,
+ Email: "[email protected]",
+ OfferManaged: true,
+ DestinationOnly: true,
+ })
+ model.width, model.height = 100, 30
+ model, _ = advanceWizard(t, model, "j")
+ model, _ = advanceWizard(t, model, "enter")
+ if model.screen != managedDisclosureScreen || model.result.Destination != DestinationAsymptote {
+ t.Fatalf("managed selection = screen %v result %#v", model.screen, model.result)
+ }
+ view := strings.Join(strings.Fields(model.View()), " ")
+ for _, want := range []string{"sends new telemetry to beacon.sh", "Nothing is forwarded", "beacon endpoint connect", "Existing local history is not uploaded"} {
+ if !strings.Contains(view, want) {
+ t.Fatalf("managed disclosure missing %q:\n%s", want, view)
+ }
+ }
+ model, _ = advanceWizard(t, model, "enter")
+ if model.screen != confirmScreen {
+ t.Fatalf("screen = %v, want confirmation", model.screen)
+ }
+ model, _ = advanceWizard(t, model, "enter")
+ if !model.result.Completed {
+ t.Fatalf("result = %#v", model.result)
+ }
+}
+
+func TestWizardHidesManagedDestination(t *testing.T) {
+ model := newWizardModel(WizardOptions{
+ SignedIn: true,
+ Email: "[email protected]",
+ OfferManaged: false,
+ DestinationOnly: true,
+ })
+ if got := model.destinations(); len(got) != 1 || got[0] != DestinationLocal {
+ t.Fatalf("destinations = %#v", got)
+ }
+}
+
+func TestWizardPresetManagedSkipsDestinationChoice(t *testing.T) {
+ model := newWizardModel(WizardOptions{
+ SignedIn: true,
+ Email: "[email protected]",
+ OfferManaged: false,
+ PresetDestination: DestinationAsymptote,
+ })
+ model, _ = advanceWizard(t, model, "enter")
+ if model.screen != managedDisclosureScreen || model.result.Destination != DestinationAsymptote {
+ t.Fatalf("preset managed = screen %v result %#v", model.screen, model.result)
+ }
+}
diff --git a/docs/cli/account-auth.mdx b/docs/cli/account-auth.mdx
index 0cb97f5f..efaa97d4 100644
--- a/docs/cli/account-auth.mdx
+++ b/docs/cli/account-auth.mdx
@@ -5,6 +5,10 @@ description: "Sign the Beacon CLI in through beacon.sh without enabling managed
Beacon account authentication is separate from endpoint forwarding. Signing in establishes your CLI identity, but it does not start Vector, register a managed endpoint, or send local telemetry anywhere.
+The interactive `beacon endpoint install` wizard requires this sign-in and launches
+the same flow when needed. System, package, MDM, CI, dry-run, and redirected-input
+installs skip the wizard and remain account-free.
+
```bash
beacon login
beacon whoami
diff --git a/docs/cli/endpoint-install.mdx b/docs/cli/endpoint-install.mdx
index eb0208b7..4bc8237a 100644
--- a/docs/cli/endpoint-install.mdx
+++ b/docs/cli/endpoint-install.mdx
@@ -47,17 +47,21 @@ By default, Beacon configures Claude Code and Codex CLI telemetry for local or c
| `--falcon-ca-file <path>` | Optional CA certificate path for Falcon LogScale HEC TLS verification |
| `--connect` | After a successful install, connect this endpoint to Beacon managed ingest: opens the dashboard to approve the device and starts the Vector forwarder. Same as running [`beacon endpoint connect`](/cli/endpoint-connect) afterwards |
-## Telemetry destination question
+## Interactive onboarding wizard
-On a first interactive install the [onboarding prompt](/cli/endpoint-onboarding) ends with one more question, where this machine's agent telemetry should go, as an arrow-key menu with three answers:
+On a first interactive install the [onboarding wizard](/cli/endpoint-onboarding)
+signs in through beacon.sh, then asks where this machine's telemetry should go:
| Answer | What happens |
|--------|--------------|
| Keep it on this machine (default) | Nothing is forwarded. Enter picks this, so forwarding is never a side effect. |
-| Forward to your own infrastructure | A SIEM, observability platform, or an S3/GCS bucket you own. The prompt prints the [log forwarding docs](/log-forwarding) and the pack commands; the install stays local until you set one up. |
-| Forward to Beacon Managed | Runs the [connect flow](/cli/endpoint-connect) after the install completes. A failed connect is reported with the retry command and never fails the install. |
+| Beacon Managed | Shows what will be sent, records the choice, and prints `beacon endpoint connect` as a separate next step. Nothing is forwarded during the wizard. |
-`--connect` is already the answer, so it skips the question. `BEACON_MANAGED_INGEST=0` hides the Beacon answer; the question is never shown non-interactively. The answer is stored in the local onboarding profile and never sent. Local and own-infrastructure answers are recorded at once and the question is not asked again. The Beacon answer is recorded only once the machine is connected, so if the install or the connection fails, the next interactive install asks again.
+`--connect` presets Beacon Managed and runs the connect flow after installation.
+`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.
+Customer-managed destinations remain available through the
+[log forwarding packs](/log-forwarding) after choosing Local.
## Examples
diff --git a/docs/cli/endpoint-onboarding.mdx b/docs/cli/endpoint-onboarding.mdx
index 97403372..93a7543c 100644
--- a/docs/cli/endpoint-onboarding.mdx
+++ b/docs/cli/endpoint-onboarding.mdx
@@ -13,59 +13,59 @@ beacon endpoint onboarding [flags]
```
The record lives in `~/.beacon/profile.json`. It survives uninstall, so reinstalling
-Beacon never asks the email and usage questions again. The destination question is
-asked again on the next interactive install until a destination is recorded; an
-Beacon answer is recorded only once the connect succeeds.
+Beacon does not repeat completed setup.
## First-run onboarding
-The first interactive `beacon endpoint install` asks two questions, how you are using Beacon and your email, then sends the answers to Beacon once. This is how we decide
-which agent runtimes and integrations to build next. It then asks a third question, where this machine's telemetry should go: keep it on the machine, forward it to your own infrastructure (a SIEM, observability platform, or an S3/GCS bucket you own, with a pointer to the [log forwarding docs](/log-forwarding)), or forward it to Beacon Managed, which runs [`beacon endpoint connect`](/cli/endpoint-connect) after the install. That answer stays local and is never sent.
+The first interactive `beacon endpoint install` opens a full-screen terminal wizard:
-What is sent, and nothing else:
+1. Sign in through beacon.sh using the same browser PKCE flow as [`beacon login`](/cli/account-auth).
+2. Choose **Local only** or **Beacon Managed**.
+3. Review the destination and confirm installation.
-| Field | Example |
-|-------|---------|
-| Email you enter | `[email protected]` |
-| Work, personal, or evaluating | `work` |
-| OS, architecture, OS version | `darwin`, `arm64`, `15.5` |
-| Beacon version and install method | `v0.0.31`, `homebrew` |
-| Names of agent runtimes on this machine | `claude_code`, `cursor` |
-| A random install ID | `64871b2b…` |
+Signing in establishes account identity only. It does not register a managed endpoint,
+start Vector, or send telemetry. Local is the default selection.
-Prompts, file contents, commands, telemetry events, and repository names are never
-sent. The endpoint agent itself stays local-only; this is one request at install time,
-not an ongoing channel.
+Choosing Beacon Managed shows a separate disclosure that new runtime and inventory
+events will be sent to beacon.sh only after you run:
-The prompt never appears non-interactively. Package postinstall scripts, MDM
+```bash
+beacon endpoint connect
+```
+
+Completing the wizard records managed intent and prints that next step; it does not
+connect automatically. Existing local history is not uploaded. The explicit
+`beacon endpoint install --connect` flag remains the exception: it presets Managed
+and runs device enrollment after installation.
+
+The wizard never appears non-interactively. Package postinstall scripts, MDM
deployments, `--system` installs, CI, `--dry-run`, and any piped or redirected stdin
-skip it silently. The destination question is also skipped on an endpoint already
-connected to Beacon. A machine onboarded before the question existed is asked it
-once, on its next interactive install.
+skip it silently. These paths remain account-free.
## Flags
| Flag | Description |
|------|-------------|
| `--reset` | Clear the onboarding record so the question is asked again |
-| `--resend` | Retry a signup that could not be delivered |
+| `--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 prompt on an install that would otherwise be
+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 only the Beacon Managed answer from the
-destination question; `beacon endpoint install --connect` still connects when asked explicitly.
+workflows. `BEACON_MANAGED_INGEST=0` hides the Beacon Managed answer; explicit
+`beacon endpoint install --connect` remains unaffected.
```bash title="Suppress the prompt"
BEACON_ONBOARDING=0 beacon endpoint install
```
-For a fleet rollout where you do want attribution but have no terminal, supply both
-answers up front and Beacon records them without prompting:
+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"
[email protected] BEACON_ONBOARDING_USAGE=work \
@@ -77,32 +77,31 @@ is reported on stderr and ignored rather than failing the install.
## Examples
-Show what was recorded, including the answer to the destination question
-(`Telemetry destination: local only …`, `own infrastructure …` or `Beacon Managed`; absent
-when it has not been asked, or when a Beacon answer has not yet been carried through to a
-connected machine):
+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` and takes
-one of three values; `--json` exposes it as `destination`:
+The answer is stored as `onboarding.destination` in `~/.beacon/profile.json`;
+`--json` exposes it as `destination`:
| Value | Printed as |
|-------|------------|
| `local` | local only (nothing forwarded) |
-| `own_infra` | own infrastructure (forwarding pack) |
| `asymptote` | Beacon Managed |
+`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 submission that could not reach Beacon. A failed submission never fails an
-install; the payload is kept and retried automatically on the next install or repair.
+Retry a legacy attribution submission that could not reach Beacon:
```bash title="Resend a queued signup"
beacon endpoint onboarding --resend