Skip to content

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

Say what Beacon Managed is for, and stop treating /dev/null as a terminal

shukieshah8f638b2d10ed
diff --git a/cli/beacon/cmd/endpoint_onboarding.go b/cli/beacon/cmd/endpoint_onboarding.go
index 64b9e431..1925f9fa 100644
--- a/cli/beacon/cmd/endpoint_onboarding.go
+++ b/cli/beacon/cmd/endpoint_onboarding.go
@@ -71,8 +71,17 @@ const runtimeProbeBudget = 2 * time.Second
// install behind it.
const submitBudget = 6 * time.Second
+// defaultOnboardingIsTTY reports whether this install can show a full-screen wizard.
+//
+// TERM=dumb is excluded alongside the isatty checks because a dumb terminal cannot
+// render the alternate screen the wizard draws into; the trace browser already made
+// that distinction and onboarding needs the same one. Both land in the existing
+// not_a_terminal skip, which is silent by contract.
func defaultOnboardingIsTTY() bool {
- return isCharDevice(os.Stdin) && isCharDevice(os.Stdout)
+ if strings.EqualFold(strings.TrimSpace(os.Getenv("TERM")), "dumb") {
+ return false
+ }
+ return isTerminal(os.Stdin) && isTerminal(os.Stdout)
}
// maybeRunOnboarding runs the one-time account and destination wizard when this
diff --git a/cli/beacon/cmd/endpoint_traces.go b/cli/beacon/cmd/endpoint_traces.go
index f25afa68..17e8a13f 100644
--- a/cli/beacon/cmd/endpoint_traces.go
+++ b/cli/beacon/cmd/endpoint_traces.go
@@ -44,7 +44,7 @@ var runTraceView = traceview.Run
func runTopLevelTraces(cmd *cobra.Command, args []string) error {
logPath := endpointTraceLogPath()
- if !isCharDevice(os.Stdin) || !isCharDevice(os.Stdout) || strings.EqualFold(os.Getenv("TERM"), "dumb") {
+ if !isTerminal(os.Stdin) || !isTerminal(os.Stdout) || strings.EqualFold(os.Getenv("TERM"), "dumb") {
result, err := dashboard.ReadTraceList(logPath, dashboard.TraceQuery{Limit: 100})
if err != nil {
return err
diff --git a/cli/beacon/cmd/root.go b/cli/beacon/cmd/root.go
index 41a43d65..5875a6ed 100644
--- a/cli/beacon/cmd/root.go
+++ b/cli/beacon/cmd/root.go
@@ -7,6 +7,7 @@ import (
"github.com/spf13/cobra"
"github.com/spf13/cobra/doc"
+ "golang.org/x/term"
"github.com/asymptote-labs/agent-beacon/cli/beacon/internal/version"
)
@@ -72,25 +73,27 @@ func shouldUseColor(out io.Writer) bool {
if !ok {
return false
}
- return isCharDevice(file)
+ return isTerminal(file)
}
-// isCharDevice reports whether a file is attached to a terminal rather than a pipe,
+// isTerminal reports whether a file is an interactive terminal rather than a pipe,
// a redirect, or a file.
//
-// Onboarding depends on this to stay out of the way of every non-interactive install
-// path: package postinstall scripts, MDM helpers, CI, and the packaging smoke tests
-// all reach `endpoint install` without a terminal, and a prompt there would hang a
-// fleet deployment.
-func isCharDevice(file *os.File) bool {
+// Onboarding and the trace browser depend on this to stay out of the way of every
+// non-interactive path: package postinstall scripts, MDM helpers, CI, and the
+// packaging smoke tests all reach `endpoint install` without a terminal, and a
+// full-screen prompt there would hang a fleet deployment.
+//
+// This used to test os.ModeCharDevice, which is also set on /dev/null and /dev/zero.
+// `beacon endpoint install < /dev/null` therefore looked interactive, launched the
+// wizard against an input that was already at EOF, and failed the install with
+// "onboarding cancelled" -- the exact deployment shape the check exists to protect.
+// A real isatty has no such hole.
+func isTerminal(file *os.File) bool {
if file == nil {
return false
}
- stat, err := file.Stat()
- if err != nil {
- return false
- }
- return stat.Mode()&os.ModeCharDevice != 0
+ return term.IsTerminal(int(file.Fd()))
}
var completionCmd = &cobra.Command{
diff --git a/cli/beacon/cmd/root_test.go b/cli/beacon/cmd/root_test.go
index e5a84134..9e880aad 100644
--- a/cli/beacon/cmd/root_test.go
+++ b/cli/beacon/cmd/root_test.go
@@ -2,6 +2,8 @@ package cmd
import (
"bytes"
+ "os"
+ "path/filepath"
"strings"
"testing"
@@ -38,3 +40,43 @@ func TestPrintRootSplash(t *testing.T) {
}
}
}
+
+// isTerminal gates the full-screen onboarding wizard and the trace browser, so
+// anything that is not a real terminal has to read as false.
+//
+// This previously tested os.ModeCharDevice, which /dev/null also sets. The result
+// was that `beacon endpoint install < /dev/null` -- an ordinary shape for a wrapper
+// script or an unattended run -- looked interactive, started the wizard against an
+// input already at EOF, and failed the install with "onboarding cancelled".
+func TestIsTerminalRejectsDevNullPipesAndRegularFiles(t *testing.T) {
+ devNull, err := os.Open(os.DevNull)
+ if err != nil {
+ t.Fatal(err)
+ }
+ defer devNull.Close()
+
+ readEnd, writeEnd, err := os.Pipe()
+ if err != nil {
+ t.Fatal(err)
+ }
+ defer readEnd.Close()
+ defer writeEnd.Close()
+
+ regular, err := os.Create(filepath.Join(t.TempDir(), "redirected.log"))
+ if err != nil {
+ t.Fatal(err)
+ }
+ defer regular.Close()
+
+ for name, file := range map[string]*os.File{
+ "/dev/null": devNull,
+ "pipe read": readEnd,
+ "pipe write": writeEnd,
+ "regular file": regular,
+ "nil": nil,
+ } {
+ if isTerminal(file) {
+ t.Fatalf("isTerminal(%s) = true, want false", name)
+ }
+ }
+}
diff --git a/cli/beacon/internal/onboarding/wizard.go b/cli/beacon/internal/onboarding/wizard.go
index 01b696e1..ee6b3876 100644
--- a/cli/beacon/internal/onboarding/wizard.go
+++ b/cli/beacon/internal/onboarding/wizard.go
@@ -98,7 +98,10 @@ func (m wizardModel) Update(message tea.Msg) (tea.Model, tea.Cmd) {
m.width, m.height = msg.Width, msg.Height
case tea.KeyMsg:
switch msg.String() {
- case "ctrl+c", "q", "esc":
+ // esc and ctrl+c cancel; "q" deliberately does not. It used to, on every
+ // screen, so a user typing q at the destination list killed the install --
+ // and no screen could ever take free text while a bare letter meant quit.
+ case "ctrl+c", "esc":
return m, tea.Quit
case "up", "k":
if m.screen == destinationScreen || m.screen == privacyScreen {
@@ -170,6 +173,7 @@ func (m wizardModel) View() string {
if width <= 0 {
width = 80
}
+ contentWidth := min(76, max(30, width-8))
var title, body string
switch m.screen {
case welcomeScreen:
@@ -191,13 +195,15 @@ func (m wizardModel) View() string {
if index == m.selected {
line = wizardChoice.Render(" ❯ " + label)
}
- rows = append(rows, line, wizardDim.Render(" "+detail))
+ rows = append(rows, line, choiceDetail(detail, contentWidth))
}
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."
+ "\n\nAfter installation, run `beacon endpoint connect`. Once connected, a local Vector forwarder sends 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:
title = "Choose what Beacon Managed receives"
var rows []string
@@ -207,7 +213,7 @@ func (m wizardModel) View() string {
if index == m.selected {
line = wizardChoice.Render(" ❯ " + label)
}
- rows = append(rows, line, wizardDim.Render(" "+detail))
+ rows = append(rows, line, choiceDetail(detail, contentWidth))
}
body = strings.Join(rows, "\n")
case confirmScreen:
@@ -222,7 +228,6 @@ func (m wizardModel) View() string {
}
}
- 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" +
@@ -233,10 +238,31 @@ func (m wizardModel) View() string {
func destinationCopy(destination string) (string, string) {
switch destination {
case DestinationAsymptote:
- return "Beacon Managed (recommended)", "Keep local JSONL and forward new events after you connect."
+ return "Beacon Managed (recommended)",
+ "One searchable history across Claude Code, Cursor, Codex and more. " +
+ "Unlimited retention, token and usage analytics. No backend to run."
default:
- return "Local only", "Opt out of managed forwarding. Nothing is sent anywhere."
+ return "Local only",
+ "Everything stays in ~/.beacon on this machine. You manage retention, " +
+ "and history is limited to this device."
+ }
+}
+
+// choiceDetail renders the dim explanation under a choice, wrapped to the card and
+// indented on every line.
+//
+// The detail used to be emitted as one pre-indented string and wrapped later with
+// the rest of the body, which indented the first line and left every continuation
+// flush against the margin. That was invisible while the captions were one-liners
+// and became wrong the moment they were not.
+func choiceDetail(detail string, width int) string {
+ const indent = " "
+ inner := max(20, width-len(indent))
+ var lines []string
+ for _, line := range strings.Split(lipgloss.NewStyle().Width(inner).Render(detail), "\n") {
+ lines = append(lines, wizardDim.Render(indent+strings.TrimRight(line, " ")))
}
+ return strings.Join(lines, "\n")
}
func privacyCopy(mode string) (string, string) {
diff --git a/cli/beacon/internal/onboarding/wizard_test.go b/cli/beacon/internal/onboarding/wizard_test.go
index a8736232..6366efca 100644
--- a/cli/beacon/internal/onboarding/wizard_test.go
+++ b/cli/beacon/internal/onboarding/wizard_test.go
@@ -81,11 +81,24 @@ func TestManagedWizardRequiresDisclosureConfirmation(t *testing.T) {
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"} {
+ for _, want := range []string{
+ "sends new telemetry to beacon.sh",
+ "Nothing is forwarded",
+ "beacon endpoint connect",
+ // 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
+ // upload. The screen used to flatly claim nothing existing is uploaded.
+ "Runtime events recorded before you connect stay on this machine",
+ "inventory snapshot",
+ } {
if !strings.Contains(view, want) {
t.Fatalf("managed disclosure missing %q:\n%s", want, view)
}
}
+ if strings.Contains(view, "Existing local history is not uploaded") {
+ t.Fatalf("the disclosure must not claim existing history is never uploaded; inventory is:\n%s", view)
+ }
model, _ = advanceWizard(t, model, "enter")
if model.screen != privacyScreen {
t.Fatalf("screen = %v, want privacy", model.screen)
@@ -146,3 +159,84 @@ func TestWizardPresetManagedSkipsDestinationChoice(t *testing.T) {
t.Fatalf("preset managed = screen %v result %#v", model.screen, model.result)
}
}
+
+// The destination captions are the only place a first-time user learns why Managed
+// exists. They used to describe the mechanism ("forward new events after you
+// connect") and named no benefit at all.
+func TestDestinationCaptionsNameTheValueNotTheMechanism(t *testing.T) {
+ managedLabel, managedDetail := destinationCopy(DestinationAsymptote)
+ if !strings.Contains(managedLabel, "Beacon Managed") {
+ t.Fatalf("managed label = %q", managedLabel)
+ }
+ for _, want := range []string{"searchable", "Unlimited retention", "analytics"} {
+ if !strings.Contains(managedDetail, want) {
+ t.Fatalf("managed detail missing %q: %q", want, managedDetail)
+ }
+ }
+ localLabel, localDetail := destinationCopy(DestinationLocal)
+ if !strings.Contains(localLabel, "Local only") {
+ t.Fatalf("local label = %q", localLabel)
+ }
+ // Local is a supported end state, not a penalty: it says where data lives and
+ // what the user takes on, and does not editorialize.
+ if !strings.Contains(localDetail, "stays in ~/.beacon") {
+ t.Fatalf("local detail should say where data lives: %q", localDetail)
+ }
+ for _, unwanted := range []string{"Opt out", "Nothing is sent"} {
+ if strings.Contains(localDetail, unwanted) {
+ t.Fatalf("local detail should read as a peer choice, found %q: %q", unwanted, localDetail)
+ }
+ }
+}
+
+// A caption that wraps must stay in its column. The detail was previously emitted
+// as one pre-indented string and wrapped with the rest of the body, which indented
+// the first line and left continuations flush against the margin.
+func TestChoiceDetailIndentsEveryWrappedLine(t *testing.T) {
+ model := newWizardModel(WizardOptions{SignedIn: true, OfferManaged: true, DestinationOnly: true})
+ model.width, model.height = 72, 30
+
+ _, detail := destinationCopy(DestinationAsymptote)
+ rendered := choiceDetail(detail, 64)
+ lines := strings.Split(rendered, "\n")
+ if len(lines) < 2 {
+ t.Fatalf("expected the managed caption to wrap at this width, got one line: %q", rendered)
+ }
+ for _, line := range lines {
+ if strings.TrimSpace(line) == "" {
+ continue
+ }
+ if !strings.HasPrefix(line, " ") {
+ t.Fatalf("wrapped caption line is not indented: %q", line)
+ }
+ }
+
+ // And the whole screen still renders every word of both captions.
+ view := strings.Join(strings.Fields(model.View()), " ")
+ for _, want := range []string{"No backend to run.", "limited to this device."} {
+ if !strings.Contains(view, want) {
+ t.Fatalf("destination screen truncated %q:\n%s", want, view)
+ }
+ }
+}
+
+// "q" used to quit from every screen, so a stray keystroke on a choice list killed
+// the install, and no screen could ever accept free text.
+func TestWizardHasNoGlobalQuitKey(t *testing.T) {
+ for _, screen := range []wizardScreen{welcomeScreen, signInScreen, destinationScreen, managedDisclosureScreen, privacyScreen, confirmScreen} {
+ model := newWizardModel(WizardOptions{SignedIn: true, OfferManaged: true})
+ model.screen = screen
+ next, command := advanceWizard(t, model, "q")
+ if command != nil {
+ t.Fatalf("q returned a command on screen %v; it must not quit", screen)
+ }
+ if next.screen != screen || next.result.Completed || next.result.NeedLogin {
+ t.Fatalf("q changed state on screen %v: %#v", screen, next.result)
+ }
+ }
+ // esc still cancels.
+ model := newWizardModel(WizardOptions{SignedIn: true, OfferManaged: true})
+ if _, command := advanceWizard(t, model, "esc"); command == nil {
+ t.Fatal("esc must still cancel the wizard")
+ }
+}
diff --git a/docs/changelog/cli.mdx b/docs/changelog/cli.mdx
index 3718b54e..69c4767e 100644
--- a/docs/changelog/cli.mdx
+++ b/docs/changelog/cli.mdx
@@ -11,6 +11,23 @@ Stay up to date with the latest changes to the Agent Beacon CLI.
## September 2026
+### Unreleased
+
+- **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
+ managed disclosure names what actually leaves the machine, since the previous
+ wording claimed no existing history was uploaded at all, which was not true of the
+ inventory snapshot.
+- **A redirected install no longer launches the wizard** · Terminal detection used a
+ character-device test, which `/dev/null` satisfies, so `beacon endpoint install <
+ /dev/null` started the full-screen wizard against an input already at end of file
+ and failed the install with "onboarding cancelled". It now uses a real terminal
+ check, and `TERM=dumb` takes the same silent skip the trace browser already used.
+- **`q` no longer quits the onboarding wizard** · It was bound to quit on every
+ screen, so one stray keystroke on a choice list ended the install. Cancel with
+ `esc`.
+
### v1.3.18 · September 21, 2026
- **Kimi Code telemetry** · Kimi Code (Moonshot AI) now has managed hook install,
diff --git a/docs/cli/endpoint-onboarding.mdx b/docs/cli/endpoint-onboarding.mdx
index 1d4c2d70..3ee17b98 100644
--- a/docs/cli/endpoint-onboarding.mdx
+++ b/docs/cli/endpoint-onboarding.mdx
@@ -20,16 +20,25 @@ Beacon does not repeat completed setup.
The first interactive `beacon endpoint install` opens a full-screen terminal wizard:
1. Sign in through beacon.sh using the same browser PKCE flow as [`beacon login`](/cli/account-auth).
-2. Choose **Local only** or **Beacon Managed**.
+2. Choose **Local only** or **Beacon Managed**. Managed is described by what it adds:
+ one searchable history across every agent, unlimited retention, token and usage
+ analytics, and no backend to run. Local keeps everything in `~/.beacon` on the
+ machine, where you manage retention and history covers only that device.
3. For Managed, choose **Standard** or **Metadata only** forwarding.
4. Review the destination and privacy mode, then confirm installation.
+Move between choices with the arrow keys, continue with <kbd>enter</kbd>, and cancel
+with <kbd>esc</kbd>.
+
Signing in establishes account identity only. It does not register a managed endpoint,
start Vector, or send telemetry. Beacon Managed is preselected; choose Local explicitly
to opt out of managed forwarding.
-Choosing Beacon Managed shows a separate disclosure that new runtime and inventory
-events will be sent to beacon.sh only after you run:
+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