diff --git a/cli/src/__tests__/onboard.test.ts b/cli/src/__tests__/onboard.test.ts
index 59a578b1f8..6aa033e251 100644
--- a/cli/src/__tests__/onboard.test.ts
+++ b/cli/src/__tests__/onboard.test.ts
@@ -1,10 +1,16 @@
 import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
-import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 import { onboard } from "../commands/onboard.js";
 import type { PaperclipConfig } from "../config/schema.js";
 
+const runCommandMock = vi.hoisted(() => vi.fn());
+
+vi.mock("../commands/run.js", () => ({
+  runCommand: runCommandMock,
+}));
+
 const ORIGINAL_ENV = { ...process.env };
 const ORIGINAL_CWD = process.cwd();
 const ORIGINAL_PATH = process.env.PATH;
@@ -102,7 +108,9 @@ describe("onboard", () => {
     delete process.env.PAPERCLIP_BIND;
     delete process.env.PAPERCLIP_BIND_HOST;
     delete process.env.PAPERCLIP_TAILNET_BIND_HOST;
+    delete process.env.PAPERCLIP_OPEN_ON_LISTEN;
     delete process.env.HOST;
+    runCommandMock.mockReset();
   });
 
   afterEach(() => {
@@ -131,6 +139,24 @@ describe("onboard", () => {
     expect(fs.existsSync(path.join(path.dirname(fixture.configPath), ".env"))).toBe(true);
   });
 
+  it("does not opt into opening a browser when --yes starts an existing setup", async () => {
+    const fixture = createExistingConfigFixture();
+
+    await onboard({ config: fixture.configPath, yes: true });
+
+    expect(runCommandMock).toHaveBeenCalledWith({ config: fixture.configPath, repair: true, yes: true });
+    expect(process.env.PAPERCLIP_OPEN_ON_LISTEN).toBeUndefined();
+  });
+
+  it("does not opt into opening a browser when --yes starts a fresh setup", async () => {
+    const configPath = createFreshConfigPath();
+
+    await onboard({ config: configPath, yes: true });
+
+    expect(runCommandMock).toHaveBeenCalledWith({ config: configPath, repair: true, yes: true });
+    expect(process.env.PAPERCLIP_OPEN_ON_LISTEN).toBeUndefined();
+  });
+
   it("backs up invalid config bytes and refuses --yes replacement", async () => {
     const configPath = createFreshConfigPath();
     const invalidBytes = Buffer.from('{"database": invalid}\n', "utf8");
diff --git a/cli/src/commands/onboard.ts b/cli/src/commands/onboard.ts
index 714741b258..f6e4be7e2c 100644
--- a/cli/src/commands/onboard.ts
+++ b/cli/src/commands/onboard.ts
@@ -477,7 +477,6 @@ export async function onboard(opts: OnboardOptions): Promise<void> {
     }
 
     if (shouldRunNow && !opts.invokedByRun) {
-      process.env.PAPERCLIP_OPEN_ON_LISTEN = "true";
       const { runCommand } = await import("./run.js");
       await runCommand({ config: configPath, repair: true, yes: true });
       return;
@@ -746,7 +745,6 @@ export async function onboard(opts: OnboardOptions): Promise<void> {
   }
 
   if (shouldRunNow && !opts.invokedByRun) {
-    process.env.PAPERCLIP_OPEN_ON_LISTEN = "true";
     const { runCommand } = await import("./run.js");
     await runCommand({ config: configPath, repair: true, yes: true });
     return;
diff --git a/docs/cli/setup-commands.md b/docs/cli/setup-commands.md
index 608bcfd285..ff6a8d070f 100644
--- a/docs/cli/setup-commands.md
+++ b/docs/cli/setup-commands.md
@@ -46,12 +46,18 @@ Start immediately after onboarding:
 pnpm paperclipai onboard --run
 ```
 
-Non-interactive defaults + immediate start (opens browser on server listen):
+Non-interactive defaults + immediate start (prints the URL without opening a browser):
 
 ```sh
 pnpm paperclipai onboard --yes
 ```
 
+Browser opening is opt-in. Set the environment variable explicitly when that is the desired behavior:
+
+```sh
+PAPERCLIP_OPEN_ON_LISTEN=true pnpm paperclipai onboard --yes
+```
+
 On an existing install, `--yes` now preserves the current config and just starts Paperclip with that setup.
 
 ## `paperclipai doctor`
diff --git a/tests/e2e/playwright.config.ts b/tests/e2e/playwright.config.ts
index 09ce17617e..30b1b06735 100644
--- a/tests/e2e/playwright.config.ts
+++ b/tests/e2e/playwright.config.ts
@@ -70,6 +70,7 @@ export default defineConfig({
       ...process.env,
       NODE_ENV: "test",
       PORT: String(PORT),
+      PAPERCLIP_OPEN_ON_LISTEN: "false",
       PAPERCLIP_API_URL: BASE_URL,
       PAPERCLIP_HOME,
       PAPERCLIP_INSTANCE_ID,
diff --git a/tests/perf/issue-detail/playwright.config.ts b/tests/perf/issue-detail/playwright.config.ts
index fe478fc8af..57c1ecd82b 100644
--- a/tests/perf/issue-detail/playwright.config.ts
+++ b/tests/perf/issue-detail/playwright.config.ts
@@ -34,6 +34,7 @@ export default defineConfig({
       ...process.env,
       NODE_ENV: "development",
       PORT: String(PORT),
+      PAPERCLIP_OPEN_ON_LISTEN: "false",
       PAPERCLIP_HOME,
       PAPERCLIP_INSTANCE_ID,
       PAPERCLIP_CONFIG,