codebase-onboarder 0.3.0 → 0.4.0

package/README.md

@@ -202,7 +202,7 @@ with it instead of orphaning a process holding the scan cache.
 Onboarder has two modes, one config file, and three ways to edit it — the CLI wizard, CLI flags, and the web UI's Server drawer all write the same validated `config.json` (`~/.config/onboarder/config.json`, mode `0600`).
 
 - **Local (default)** — binds to loopback only, asks for no credentials. The safe default.
-- **Self-hosted** — a fresh setup binds `0.0.0.0` for direct LAN/VPS access; every API call requires a Bearer access key. Re-running setup preserves an existing loopback tunnel layout. Rotate the key with `onboarder config key rotate`; the old key dies on the next request.
+- **Self-hosted** — a fresh setup binds `0.0.0.0` for direct LAN/VPS access. Any IP-literal address is accepted, while arbitrary Host names are not. Remote browsers get a themed access-key login page and exchange the key for a 7-day signed `HttpOnly`, `SameSite=Strict` session cookie; true localhost requests skip login. API clients can continue using `Authorization: Bearer <access-key>`. Rotate the key with `onboarder config key rotate`; the old key and every old browser session die on the next request.
 
 ```bash
 onboarder setup                          # interactive wizard
@@ -212,7 +212,13 @@ onboarder config show                    # current settings (key masked)
 onboarder config set host 0.0.0.0        # direct VPS/LAN access (domain optional)
 onboarder config set port 4311           # move away from a busy port
 onboarder config key rotate              # mint a new access key
-onboarder status                         # running PID, stopped, or unmanaged port owner
+onboarder start                          # foreground; Ctrl-C stops it
+onboarder start background               # detached; keeps running after you close the terminal
+onboarder logs                           # last 40 log lines  (-n <count>, -f to follow)
+onboarder start startup install          # also start automatically at every login
+onboarder start startup status           # is a login item installed, and is it live?
+onboarder start startup remove           # take the login item back out
+onboarder status                         # running PID, mode, uptime, stopped, or unmanaged port owner
 onboarder stop                           # stop a PID-file-managed instance
 onboarder restart                        # graceful stop, then start
 onboarder tunnel cloudflare              # expose via a Cloudflare quick tunnel
@@ -223,7 +229,41 @@ onboarder https status                   # domain, URL, Caddyfile, and Caddy sta
 onboarder doctor                         # config, access key, ports, DNS, TLS, and tunnels
 ```
 
-A fresh self-hosted setup uses `0.0.0.0`, so a VPS is reachable at `http://<server-ip>:<port>` without a reverse proxy. A domain is optional for direct-IP access. If a domain is entered, setup asks whether to enable automatic HTTPS.
+### Running it in the background
+
+`onboarder start` runs in the foreground on purpose: it is a normal command, and Ctrl-C stops it. When you want the server to outlive the terminal, use `start background`. It re-launches the same CLI as a detached process with its output going to `onboarder.log` beside your config, then **waits for the server to actually answer** `/api/health` before reporting success. A port conflict comes back as a failure with the log tail attached, not as a cheerful green light that dies a second later.
+
+```bash
+onboarder start background   # returns once it is serving
+onboarder logs -f            # watch it, Ctrl-C to stop watching (not the server)
+onboarder stop               # stop it
+```
+
+Log lines are column-aligned — a fixed-width local timestamp, a fixed-width level, then the message — so a wall of requests stays scannable:
+
+```
+16:09:38.985  INFO   GET /api/health 200 (1ms)
+16:09:46.460  INFO   GET /nope 404 (1ms)
+16:10:21.925  WARN   config port=4310 reason="already in use"
+```
+
+Set `ONBOARDER_LOG=json` for one JSON object per line instead (the log file is plain text by default so it stays readable; `--json` on `status`/`logs` is the machine-readable surface).
+
+### Starting at login
+
+`onboarder start startup install` registers Onboarder with whatever your OS uses for login items, and never asks for `sudo`:
+
+| Platform | What it writes | How it loads |
+|---|---|---|
+| macOS | `~/Library/LaunchAgents/com.onboarder.server.plist` | `launchctl bootstrap gui/$UID` |
+| Linux | `~/.config/systemd/user/onboarder.service` | `systemctl --user enable --now` |
+| Windows | `%APPDATA%\...\Startup\Onboarder.cmd` | the file *is* the registration |
+
+All three run the same `onboarder start --config <your config>`, so a login-started server is indistinguishable from a hand-started one — same config, same pid file, same `onboarder stop`. The generated unit uses `Restart=on-failure` (and launchd's `KeepAlive`/`SuccessfulExit=false`), so a crash is restarted but a deliberate `onboarder stop` stays stopped. `onboarder start startup remove` unloads and deletes it; a running server is left alone. On a platform with no known mechanism, the command says so instead of pretending.
+
+A fresh self-hosted setup uses `0.0.0.0`, so a VPS is reachable at `http://<server-ip>:<port>` without a reverse proxy. The server accepts IPv4 and IPv6 IP literals, including a public address that reaches the host through provider NAT, but still rejects arbitrary DNS Host headers. A domain is optional for direct-IP access. If a domain is entered, setup asks whether to enable automatic HTTPS.
+
+When a remote browser opens the URL, Onboarder shows its themed sign-in page. The access key is sent in a POST body—not in the URL—and the browser stores only the signed session cookie. Opening the same server through `http://localhost:<port>` on that machine skips the page. Caddy and tunnel connections remain authenticated because their public Host is not loopback.
 
 For trusted HTTPS, DNS must already point the domain to the VPS and inbound TCP `80` and `443` must be allowed in both the cloud security group/NSG and the host firewall. On Ubuntu:
 
@@ -236,7 +276,7 @@ onboarder https check
 onboarder https setup
 ```
 
-Onboarder writes a private `Caddyfile` beside `config.json`, validates it, and asks Caddy to obtain and renew the certificate. It never runs `sudo` or installs packages silently. Caddy proxies `https://map.example.com` to `http://127.0.0.1:4310`; Onboarder continues to enforce the access key on every API call. A bare public IP cannot use a normal trusted domain certificate.
+Onboarder writes a private `Caddyfile` beside `config.json`, validates it, and asks Caddy to obtain and renew the certificate. It never runs `sudo` or installs packages silently. Caddy proxies `https://map.example.com` to `http://127.0.0.1:4310`; Onboarder recognizes the connection as remote and shows the access-key login page. A bare public IP cannot use a normal trusted domain certificate.
 
 If startup reports `EADDRINUSE`, run `onboarder status` first. If it identifies an Onboarder PID, use `onboarder stop` or `onboarder restart`; otherwise inspect the unrelated listener with `ss -ltnp` or `lsof -i :4310`, or choose another port. The error names these recovery commands instead of printing only the raw Node error.
 
@@ -253,8 +293,13 @@ codebase-onboarder/
 ├── server/          # Zero-dependency Node.js HTTP server
 │   ├── index.js     # createServer / startServer / startup banner
 │   ├── config.js    # Settings schema, normalization, atomic 0600 writes
-│   ├── pidfile.js   # PID ownership for status / stop / restart
-│   ├── router.js    # Route table, live per-request settings, Bearer gate
+│   ├── pidfile.js   # PID + run record (mode, url, log) for status / stop / restart
+│   ├── daemon.js    # Detached background start, log file, readiness probe
+│   ├── startup.js   # Login items: launchd plist / systemd --user unit / Startup folder
+│   ├── logger.js    # Aligned-text or JSON log lines from one entry shape
+│   ├── router.js    # Route table, live per-request settings, auth & CSRF gates
+│   ├── auth.js      # Signed HttpOnly browser sessions
+│   ├── apiAuth.js   # Login/status/logout endpoints
 │   ├── apiSettings.js# GET/PUT /api/settings, key rotation
 │   ├── tunnel.js    # Cloudflare & Tailscale status/commands
 │   ├── https.js     # Caddy config, ACME/TLS readiness & lifecycle
@@ -269,8 +314,9 @@ codebase-onboarder/
 ├── public/          # Frontend client application
 │   ├── js/          # Vanilla ES modules (State, Inspector, Views, Settings)
 │   ├── vendor/      # Vendored Mermaid & Monaco Editor (Offline)
-│   └── index.html   # Main application interface
-└── tests/           # Comprehensive node:test suite (560 unit tests)
+│   ├── index.html   # Main application interface
+│   └── login.html   # Self-hosted access-key sign-in
+└── tests/           # Comprehensive node:test suite (565 tests)
 ```
 
 ---
@@ -280,7 +326,7 @@ codebase-onboarder/
 Onboarder includes a comprehensive automated test suite built with Node's native test runner:
 
 ```bash
-# Run all 560 tests
+# Run all 565 tests
 npm test
 ```
 

package/cli/commands.js

@@ -12,13 +12,15 @@ import { spawn } from 'node:child_process';
 
 import {
   DEFAULT_SETTINGS, configPath, configExists, readSettings, writeSettings,
-  publicSettings, serverUrls, maskAccessKey,
+  publicSettings, serverUrls, maskAccessKey, isLoopbackHost,
 } from '../server/config.js';
 import { startServer } from '../server/index.js';
-import { pidIsAlive, readPidFile, removePidFile } from '../server/pidfile.js';
+import { pidIsAlive, readPidFile, removePidFile, readRunInfo, runInfoPath } from '../server/pidfile.js';
+import { logPath, rotateLogIfNeeded, tailLog, followLog, logExists, spawnDetached, waitForPidFile, waitForReady } from '../server/daemon.js';
+import { installStartup, removeStartup, startupStatus, startupTarget } from '../server/startup.js';
 import { tunnelStatus, cloudflareCommand, tailscaleCommand, installHint, findOnPath } from '../server/tunnel.js';
 import { caddyRun, caddyValidate, httpsReadiness, httpsStatus, writeCaddyfile } from '../server/https.js';
-import { bold, cyan, dim, ok, warn, bad, kv, tick, cross, dash, welcomeBanner } from './ui.js';
+import { bold, cyan, dim, ok, warn, bad, paint, kv, tick, cross, dash, welcomeBanner, panel, row, hint } from './ui.js';
 import { buildSteps, unansweredSteps, defaultOf, applyFlags, answersToSettings, summaryLines } from './wizard.js';
 import { runSteps, WizardCancelled } from './prompt.js';
 
@@ -41,6 +43,9 @@ export async function runSetup({ flags = {}, out = console.log, err = console.er
       printSummary(out, settings, { revealKey: Boolean(patchHasNewKey(flags)) });
     }
     await printTunnelFollowup(out, settings);
+    // `start` may be the flag `--start` (true) or the mode a subcommand asked
+    // for ('background') — both mean "boot it now", differently.
+    if (flags.start === 'background') return runStartBackground({ flags, out, err });
     if (flags.start) return runStart({ flags, out, err });
     return 0;
   }
@@ -95,9 +100,9 @@ export async function runSetup({ flags = {}, out = console.log, err = console.er
   }
   await printTunnelFollowup(out, settings);
 
-  if (flags.start || await confirm(out, 'Start Onboarder now?', true)) {
+  if (flags.start === 'background' || (!flags.start && await confirm(out, 'Start Onboarder now?', true))) {
     out('');
-    return runStart({ flags, out, err });
+    return flags.start === 'background' ? runStartBackground({ flags, out, err }) : runStart({ flags, out, err });
   }
   out(dim(settings.https
     ? '  Later: `onboarder start` (starts Caddy automatically), or `onboarder https status`'
@@ -145,6 +150,38 @@ async function printTunnelFollowup(out, settings) {
 
 // ---------------------------------------------------------------- start ---
 
+// What the person is about to be looking at, as a titled panel instead of a
+// loose run of lines. One function serves the foreground banner and the
+// background confirmation, so "what does `onboarder start` tell me" has exactly
+// one answer no matter which mode you used.
+export function serverDetails(started, { configFile, pid = null, mode = 'foreground', logFile = '' } = {}) {
+  const { settings, host, port } = started;
+  const urls = serverUrls(settings);
+  const rows = [
+    row('URL', bold(cyan(urls.local))),
+    row('Bind', `${host}:${port}`),
+    row('Mode', settings.mode === 'self-hosted'
+      ? (isLoopbackHost(host) ? 'self-hosted (loopback — use a tunnel for remote access)' : 'self-hosted (network reachable, access key required)')
+      : 'local (this machine only)'),
+  ];
+  if (urls.network) rows.push(row('Network', urls.network));
+  if (urls.domain) rows.push(row('Public', urls.domain));
+  if (settings.mode === 'self-hosted') {
+    rows.push(row('Access key', settings.accessKey ? maskAccessKey(settings.accessKey) : bad('NOT SET — every API call is refused')));
+  }
+  rows.push(row('PID', String(pid ?? process.pid)));
+  rows.push(row('Config', dim(configFile || '')));
+  if (logFile) rows.push(row('Logs', dim(logFile)));
+  return { rows, urls, mode };
+}
+
+function printServerDetails(out, started, options) {
+  const { rows } = serverDetails(started, options);
+  out('');
+  out(panel('Onboarder is running', rows));
+  out('');
+}
+
 export async function runStart({ flags = {}, out = console.log, err = console.error } = {}) {
   const file = flags.config || configPath();
   if (!await configExists(file)) {
@@ -165,7 +202,9 @@ export async function runStart({ flags = {}, out = console.log, err = console.er
   }
   if (recorded) removePidFile(file, recorded);
 
-  const started = await startServer({ configFile: file, log: out });
+  // `quiet`: the CLI prints its own details panel below, so the loose banner
+  // would be the same facts twice. `node server/index.js` still gets the banner.
+  const started = await startServer({ configFile: file, log: () => {}, openBrowser: false });
   if (started.settings.https) {
     out('');
     const httpsCode = await runHttps('setup', { flags, out: flags.json ? () => {} : out, err });
@@ -175,13 +214,116 @@ export async function runStart({ flags = {}, out = console.log, err = console.er
     }
   }
   if (flags.json) out(JSON.stringify({ host: started.host, port: started.port, url: serverUrls(started.settings).local }));
+  // `start` foreground prints the details itself rather than letting
+  // `startServer` print the old loose banner — the panel replaces it. The
+  // background child lands here too (that is the point of reusing this path),
+  // and ONBOARDER_BACKGROUND is what tells the two apart: one is attached to a
+  // terminal you are about to close, the other is already detached from it.
+  printServerDetails(out, started, { configFile: file, mode: 'foreground' });
+  if (process.env.ONBOARDER_LAUNCH) {
+    // Started by launchd/systemd/the Startup folder: these lines are going into
+    // a log file nobody is watching, so they say what the supervisor is doing
+    // rather than telling a person to press Ctrl-C.
+    out(dim(`  Launched at login by ${process.env.ONBOARDER_LAUNCH}. This process is supervised — stop it with \`onboarder stop\`.`));
+  } else if (process.env.ONBOARDER_BACKGROUND) {
+    out(dim('  Started in the background — this process is now independent of any terminal.'));
+  } else {
+    out(dim('  Running in the foreground. Ctrl-C stops it; closing this terminal stops it too.'));
+    out(dim('  To keep it alive after you close the terminal: ') + cyan('onboarder start background'));
+  }
+  out('');
   // The listening server holds the event loop; resolve so callers/tests know
   // we are up, but leave the process running.
   return { ...started, code: 0 };
 }
 
+// `onboarder start background` — same server, no terminal attached. The child is
+// an ordinary foreground `start`; all this does is detach it and then *wait for
+// it to answer* before reporting success, so a bind failure surfaces here as a
+// failure with the log tail attached rather than a cheerful lie.
+export async function runStartBackground({ flags = {}, out = console.log, err = console.error } = {}) {
+  const file = flags.config || configPath();
+  if (!await configExists(file) && process.stdout.isTTY && !flags.nonInteractive) {
+    out(dim('  No settings yet — running setup first.'));
+    return runSetup({ flags: { ...flags, start: 'background' }, out, err });
+  }
+  const recorded = readPidFile(file);
+  if (recorded && pidIsAlive(recorded)) {
+    err(`  Onboarder is already running (PID ${recorded}).`);
+    err(dim('    Use `onboarder status`, `onboarder stop`, or `onboarder restart`.'));
+    return 1;
+  }
+  if (recorded) removePidFile(file, recorded);
+
+  const settings = await readSettings(file);
+  const log = logPath(file);
+  await rotateLogIfNeeded(log);
+
+  spawnDetached({ configFile: file, log });
+  const pid = await waitForPidFile(file, { timeoutMs: flags.timeout ? Number(flags.timeout) * 1000 : 20000 });
+  const urls = serverUrls(settings);
+  const ready = pid ? await waitForReady(new URL('/api/health', urls.local).toString(), { timeoutMs: 8000 }) : false;
+
+  if (!ready) {
+    // Two different failures with two different fixes, so they are reported
+    // differently. No pid record means the child never finished binding — the
+    // log holds the reason (a busy port, an invalid config). A live pid that will
+    // not answer means it bound and then something in front of it is in the way
+    // (a proxy, a firewall), and no amount of log-reading will show that.
+    if (!pid) {
+      err(bad('  Onboarder did not start in the background.'));
+      const tail = await tailLog(log, 15);
+      if (tail.length) {
+        err(dim(`  Last lines of ${log}:`));
+        for (const line of tail) err('    ' + line);
+      }
+      err(dim('    Fix the cause above, then run `onboarder start background` again.'));
+    } else {
+      err(bad(`  Onboarder is running (PID ${pid}) but ${urls.local} is not answering.`));
+      err(dim(`    Its log is ${log}. If a proxy or firewall fronts this port, check that first.`));
+      err(dim('    Otherwise: `onboarder stop`, then `onboarder start background` again.'));
+    }
+    return 1;
+  }
+
+  if (flags.json) {
+    out(JSON.stringify({ background: true, pid, url: urls.local, log, configFile: file }, null, 2));
+    return 0;
+  }
+
+  out('');
+  out(panel('Onboarder is running in the background', [
+    row('URL', bold(cyan(urls.local))),
+    row('PID', String(pid)),
+    row('Mode', 'background — survives closing this terminal'),
+    row('Logs', dim(log)),
+    row('Config', dim(file)),
+  ]));
+  out('');
+  out(dim('  Follow the log: ') + cyan('onboarder logs -f'));
+  out(dim('  Stop it:         ') + cyan('onboarder stop'));
+  out(dim('  Check on it:     ') + cyan('onboarder status'));
+  out('');
+  return 0;
+}
+
+
 // ------------------------------------------------------------- lifecycle ---
 
+// Panel rows carry their own inline marker rather than the `tick`/`cross`/`dash`
+// constants: those bake in a two-column indent for standalone lines, which would
+// push the first row out of the panel's label column.
+const MARK = { yes: (s) => paint('✓ ', 'green') + s, no: (s) => paint('– ', 'gray') + s, warn: (s) => paint('! ', 'yellow') + s };
+
+// How a live instance presents itself, in one sentence per mode. The point of
+// the sentence is the thing someone actually needs to know: can I close my
+// terminal, or will that kill it?
+const MODE_NOTES = {
+  background: 'background — survives closing the terminal',
+  startup: 'started at login — the OS restarts it if it stops',
+  foreground: 'foreground — stops when you press Ctrl-C or close the terminal',
+};
+
 export async function runStatus({ flags = {}, out = console.log } = {}) {
   const file = flags.config || configPath();
   const pid = readPidFile(file);
@@ -190,6 +332,9 @@ export async function runStatus({ flags = {}, out = console.log } = {}) {
   try { settings = await readSettings(file); } catch { /* defaults are still meaningful */ }
   const portBusy = settings ? !(await portIsFree(settings.host, settings.port)) : false;
   if (pid && !running) removePidFile(file, pid);
+  // The pid says whether it is up; the run record says *how* it came up, which
+  // is what tells someone whether closing their terminal will kill it.
+  const info = running ? readRunInfo(file) : null;
   const result = {
     running: Boolean(running || portBusy),
     pid: running ? pid : null,
@@ -197,21 +342,53 @@ export async function runStatus({ flags = {}, out = console.log } = {}) {
     portBusy,
     managed: Boolean(running),
     configFile: file,
+    mode: running ? (info?.mode || 'foreground') : null,
+    url: running ? (info?.url || (settings ? serverUrls(settings).local : null)) : null,
+    uptimeMs: running && info?.startedAt ? Date.now() - Date.parse(info.startedAt) : null,
+    log: running && info?.log ? info.log : null,
+    startup: (await startupStatus()).installed,
   };
   if (flags.json) {
     out(JSON.stringify(result, null, 2));
   } else {
     out('');
-    out(bold('  Onboarder status'));
-    if (running) out(`${tick}Running    PID ${pid}`);
-    else if (portBusy) out(`${warn('!')}Port busy  ${result.port} (no Onboarder PID record)`);
-    else out(`${dash}Stopped`);
-    out(kv('Config', file));
-    if (result.portBusy && !running) out(dim('    Inspect it with `ss -ltnp` or `lsof -i :' + settings.port + '` before stopping another process.'));
+    out(panel('Onboarder status', [
+      row('State', running
+        ? MARK.yes(`Running (PID ${pid})`)
+        : portBusy
+          ? MARK.warn(`Port busy — ${result.port}, but no Onboarder process record`)
+          : MARK.no('Stopped')),
+      ...(running ? [
+        row('URL', cyan(result.url || '')),
+        row('Mode', MODE_NOTES[result.mode] || MODE_NOTES.foreground),
+        ...(result.uptimeMs ? [row('Uptime', humanDuration(result.uptimeMs))] : []),
+        ...(result.log ? [row('Logs', dim(result.log))] : []),
+      ] : []),
+      row('Config', dim(file)),
+      row('At login', result.startup ? MARK.yes('Enabled') : MARK.no('Not enabled — `onboarder start startup install`')),
+      ...(result.portBusy && !running
+        ? [hint('Inspect the listener with `ss -ltnp` or `lsof -i :' + settings.port + '` before stopping another process.')]
+        : []),
+    ]));
+    out('');
   }
   return 0;
 }
 
+// "3d 4h", "12m 5s" — coarse on purpose. Precision past the second is noise on
+// something a person glances at.
+export function humanDuration(ms) {
+  const total = Math.max(0, Math.floor(ms / 1000));
+  const days = Math.floor(total / 86400);
+  const hours = Math.floor((total % 86400) / 3600);
+  const minutes = Math.floor((total % 3600) / 60);
+  const seconds = total % 60;
+  if (days) return `${days}d ${hours}h`;
+  if (hours) return `${hours}h ${minutes}m`;
+  if (minutes) return `${minutes}m ${seconds}s`;
+  return `${seconds}s`;
+}
+
 function waitForExit(pid, timeoutMs = 5000) {
   return new Promise((resolve) => {
     const started = Date.now();
@@ -274,6 +451,109 @@ export async function runRestart(options = {}) {
   return runStart(options);
 }
 
+// ----------------------------------------------------------------- logs ---
+
+// `onboarder logs` — the answer to "it is running in the background, what is it
+// doing?". Prints the tail of the same file the background child writes, and
+// `-f` follows it. Line-oriented and level-colored, so a wall of request logs
+// stays scannable instead of being one undifferentiated block.
+export async function runLogs({ flags = {}, out = console.log, err = console.error } = {}) {
+  const file = flags.config || configPath();
+  const log = logPath(file);
+  const lines = flags.lines === undefined ? 40 : Math.max(1, Number(flags.lines) || 40);
+  if (!await logExists(log)) {
+    if (flags.json) out(JSON.stringify({ log, exists: false, lines: [] }, null, 2));
+    else {
+      err(`  No log file yet at ${log}.`);
+      err(dim('    A foreground `onboarder start` prints to the terminal; only `onboarder start background` writes this file.'));
+    }
+    return flags.json ? 0 : 1;
+  }
+  if (!flags.follow) {
+    const tail = await tailLog(log, lines);
+    if (flags.json) { out(JSON.stringify({ log, exists: true, lines: tail }, null, 2)); return 0; }
+    out('');
+    out(bold(`  ${log}`) + dim(`  (last ${tail.length} of ${lines})`));
+    out('');
+    for (const line of tail) out('  ' + line);
+    out('');
+    return 0;
+  }
+  if (flags.json) { err('  --follow and --json do not combine; pick one.'); return 2; }
+  out('');
+  out(bold(`  Following ${log}`) + dim('  (Ctrl-C to stop)'));
+  out('');
+  const stop = followLog(log, (line) => out('  ' + line), { from: 'start' });
+  const finish = () => { stop(); process.exit(0); };
+  process.once('SIGINT', finish);
+  await new Promise((resolve) => process.once('exit', resolve));
+  return 0;
+}
+
+// -------------------------------------------------------------- startup ---
+
+// `onboarder start startup` — run at login, not just right now. Three verbs
+// because the three actions are genuinely different: `install` writes the
+// artifact and hands it to the OS, `remove` takes it back out, `status` only
+// looks. `install` also starts it once so the person is not left waiting for the
+// next reboot to find out whether it worked.
+export async function runStartup(action = 'status', { flags = {}, out = console.log, err = console.error } = {}) {
+  const file = flags.config || configPath();
+  const target = startupTarget();
+  const log = logPath(file);
+
+  if (action === 'install' || action === 'enable' || action === 'on') {
+    const result = await installStartup({ configFile: file, log, target });
+    if (!result.ok) {
+      err(bad('  Could not install the startup entry.'));
+      err('    ' + (result.reason || result.output || result.error || 'unknown error'));
+      return 1;
+    }
+    out(tick + `Onboarder will start at login (${target.hint}).`);
+    out(kv('Startup file', result.path));
+    if (result.output) out(dim('    ' + result.output.split('\n').slice(-2).join('\n    ')));
+    out('');
+    out(dim('  Start it right now too: ') + cyan('onboarder start background'));
+    out(dim('  Turn it off again:      ') + cyan('onboarder start startup remove'));
+    out('');
+    return 0;
+  }
+
+  if (action === 'remove' || action === 'disable' || action === 'off' || action === 'uninstall') {
+    const status = await startupStatus(target);
+    if (!status.installed) {
+      out(dash + 'No startup entry is installed — nothing to remove.');
+      return 0;
+    }
+    const result = await removeStartup({ target });
+    if (!result.ok) { err(bad('  Could not remove the startup entry: ' + (result.reason || 'unknown error'))); return 1; }
+    out(tick + 'Startup entry removed. A running server is untouched — use `onboarder stop` for that.');
+    out(kv('Removed', result.path));
+    out('');
+    return 0;
+  }
+
+  if (action === 'status' || action === undefined) {
+    const status = await startupStatus(target);
+    if (flags.json) { out(JSON.stringify(status, null, 2)); return status.installed ? 0 : 1; }
+    out('');
+    out(panel('Onboarder at login', [
+      row('State', status.installed
+        ? (status.active ? MARK.yes('Enabled and running') : MARK.warn('Enabled, not running'))
+        : MARK.no('Not enabled')),
+      row('How', status.detail),
+      ...(status.path ? [row('File', dim(status.path))] : []),
+      ...(status.supported ? [hint(status.installed
+        ? 'Remove it with `onboarder start startup remove`.'
+        : 'Enable it with `onboarder start startup install`.')] : []),
+    ]));
+    out('');
+    return status.installed ? 0 : 1;
+  }
+
+  throw new Error('Usage: onboarder start startup [install|remove|status]');
+}
+
 // --------------------------------------------------------------- config ---
 
 // Keys `config set` may touch — the same allow-list the HTTP API enforces, so
@@ -628,7 +908,7 @@ export async function runTunnel(kind, { flags = {}, out = console.log, err = con
       if (m && !announced) {
         announced = true;
         out(tick + 'Public URL: ' + bold(m[0]));
-        out(dim('    Anyone with the URL still needs the access key: ' + m[0] + '?key=<your-key>'));
+        out(dim('    Anyone with the URL still needs the access key: ' + m[0]));
       }
       if (flags.verbose) process.stderr.write(text);
     });

package/cli/main.js

@@ -8,7 +8,7 @@ import fs from 'node:fs';
 import { parseArgs } from 'node:util';
 
 import {
-  runSetup, runStart, runStatus, runStop, runRestart,
+  runSetup, runStart, runStartBackground, runStartup, runLogs, runStatus, runStop, runRestart,
   runConfig, runConfigKey, runConfigReset, runDoctor, runTunnel, runHttps,
 } from './commands.js';
 
@@ -20,7 +20,10 @@ const HELP = `
   Usage
     onboarder                     Start the server (runs setup first if needed)
     onboarder setup | onboard     Configure interactively (the wizard)
-    onboarder start               Start the server
+    onboarder start               Start in the foreground (Ctrl-C stops it)
+    onboarder start background    Start detached — keeps running after you close the terminal
+    onboarder start startup       Run automatically at login [install|remove|status]
+    onboarder logs                Show recent log lines  (-n <count>, -f to follow)
     onboarder status              Show whether the server is running
     onboarder stop                Stop the running server
     onboarder restart             Stop and start again
@@ -48,11 +51,16 @@ const HELP = `
   Also accepted
     help | --help       onboarder help | onboarder --help
     config | config show
+    bg | detached       alias for start background
+    fg | foreground     alias for start
 
   Examples
     onboarder setup
+    onboarder start background          # leave it running, close the terminal
+    onboarder logs -f                   # watch what it is doing
+    onboarder start startup install     # also start it every time you log in
+    onboarder start background && open http://localhost:4310
     onboarder setup --non-interactive --mode local --port 4310
-    onboarder setup --non-interactive --mode self-hosted --host 0.0.0.0
     onboarder setup --non-interactive --mode self-hosted --domain map.example.com --https --start
     onboarder config set tunnel.cloudflare true && onboarder tunnel cloudflare
 `;
@@ -82,6 +90,9 @@ const OPTIONS = {
   cloudflare: { type: 'boolean' },
   tailscale: { type: 'boolean' },
   'auto-open': { type: 'boolean' },
+  lines: { type: 'string', short: 'n' },
+  follow: { type: 'boolean', short: 'f' },
+  timeout: { type: 'string' },
 };
 
 // parseArgs speaks kebab-case; the wizard's flags speak camelCase.
@@ -115,8 +126,33 @@ export async function main(argv = process.argv.slice(2)) {
         console.log(HELP);
         return 0;
       case undefined:
+        return codeOf(await runStart({ flags }));
       case 'start':
+        // `onboarder start [background|fg|startup [action]]`. The sub-verb is a
+        // positional, not a flag, because `onboarder start` has to keep working
+        // exactly as it did and `startup install` is a different verb from
+        // `start`.
+        if (sub === 'background' || sub === 'bg' || sub === 'daemon' || sub === 'detached') {
+          return codeOf(await runStartBackground({ flags }));
+        }
+        if (sub === 'startup' || sub === 'login' || sub === 'autostart') {
+          return codeOf(await runStartup(rest[0] || 'status', { flags }));
+        }
+        if (sub === 'fg' || sub === 'foreground') return codeOf(await runStart({ flags }));
+        if (sub === 'status') return codeOf(await runStatus({ flags }));
+        if (sub === 'stop') return codeOf(await runStop({ flags }));
+        if (sub === 'logs') return codeOf(await runLogs({ flags }));
+        if (sub) {
+          console.error('  Unknown start mode: ' + sub + '\n' + HELP);
+          return 2;
+        }
         return codeOf(await runStart({ flags }));
+      case 'logs':
+      case 'log':
+        return codeOf(await runLogs({ flags }));
+      case 'startup':
+      case 'autostart':
+        return codeOf(await runStartup(sub || 'status', { flags }));
       case 'status':
         return codeOf(await runStatus({ flags }));
       case 'stop':

package/cli/ui.js

@@ -53,3 +53,37 @@ export function kv(label, value) {
 export const tick = ok('  ✓ ');
 export const cross = bad('  ✗ ');
 export const dash = dim('  – ');
+
+// Visible width, ANSI codes excluded. Padding has to be computed on what the
+// terminal *shows*, not on the bytes we wrote, or every colored row grows a
+// few columns and the column stops being a column.
+export function width(text) {
+  return String(text).replace(/\x1b\[[0-9;]*m/g, '').length;
+}
+
+// A titled block of rows. The box is drawn from the widest row rather than a
+// fixed 80 columns, so it stays aligned in a narrow terminal and does not stretch
+// across a wide one.
+export function panel(title, rows, { indent = '  ' } = {}) {
+  const labelWidth = Math.max(...rows.map((r) => width(r.label ?? '')), 0);
+  // Every row starts two columns in; the label column is then as wide as the
+  // longest label, so all the values line up regardless of label length.
+  const body = rows.map((r) => r.hint
+    ? '  ' + ' '.repeat(labelWidth + 4) + dim(r.hint)
+    : '  ' + paint((r.label ?? '').padEnd(labelWidth), 'gray') + '  ' + (r.value ?? ''));
+  // The frame is sized from its contents: a long path widens the box instead of
+  // spilling out of it, and a short one does not stretch to 80 columns.
+  const inner = Math.max(title.length + 4, ...body.map(width), 24);
+  const top = '┌─ ' + bold(title) + ' ' + '─'.repeat(Math.max(1, inner - title.length - 3)) + '┐';
+  const bottom = '└' + '─'.repeat(inner) + '┘';
+  return [top, ...body, bottom].map((line) => indent + (line === top || line === bottom ? paint(line, 'gray') : line)).join('\n');
+}
+
+// A one-line hint under a row, wrapped in the panel's dim voice.
+export const hint = (text) => ({ hint: text });
+
+// Multi-line values (a command, a path list) still align on the first line.
+export function row(label, value) {
+  return { label, value: String(value) };
+}
+

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "codebase-onboarder",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "Drop a path. Get a map. A zero-dependency codebase visualizer with a CLI onboarding wizard, a web UI, and an optional key-gated self-hosted mode.",
   "type": "module",
   "bin": {

package/public/index.html

@@ -411,13 +411,14 @@
       <button class="btn btn-ghost btn-sm" id="srvRotate" title="Mint a new key; the old one dies immediately">Rotate</button>
     </div>
     <div class="server-fresh-key" id="srvFreshKeyRow" hidden>
-      <p class="drawer-fine">New key — shown once. It is already saved in this browser:</p>
+      <p class="drawer-fine">New key — shown once. This browser has been signed in with it:</p>
       <div class="mcp-config-row">
         <input type="text" class="text-input mcp-config-input" id="srvFreshKey" readonly spellcheck="false">
         <button class="btn btn-ghost btn-sm" id="srvCopyKey">Copy</button>
       </div>
     </div>
     <p class="drawer-fine" id="srvKeyHint"></p>
+    <button class="btn btn-ghost btn-sm" id="srvLogout">Sign out this browser</button>
   </div>
 
   <div class="server-section">