codebase-onboarder 0.1.0 → 0.3.0

package/README.md

@@ -3,7 +3,7 @@
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
 [![Node.js](https://img.shields.io/badge/node-%3E%3D20.0.0-brightgreen.svg)](https://nodejs.org/)
 [![Zero Dependencies](https://img.shields.io/badge/runtime%20dependencies-0-success.svg)](package.json)
-[![Tests](https://img.shields.io/badge/tests-546%20passing-brightgreen.svg)](tests/)
+[![Tests](https://img.shields.io/badge/tests-560%20passing-brightgreen.svg)](tests/)
 
 > **Drop a path. Get a map.**  
 > A lightweight, zero-dependency codebase visualizer and architectural map generator that runs entirely on your local machine.
@@ -202,20 +202,45 @@ 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** — reachable on your network or domain; every API call requires a Bearer access key. Rotate it from the drawer or with `onboarder config key rotate`; the old key dies on the next request, no restart needed.
+- **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.
 
 ```bash
-onboarder setup                          # interactive wizard (OpenClaw-style)
+onboarder setup                          # interactive wizard
 onboarder setup --mode self-hosted \
-  --domain map.example.com --non-interactive
+  --domain map.example.com --https --start
 onboarder config show                    # current settings (key masked)
-onboarder config set domain map.example.com
+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 stop                           # stop a PID-file-managed instance
+onboarder restart                        # graceful stop, then start
 onboarder tunnel cloudflare              # expose via a Cloudflare quick tunnel
-onboarder doctor                         # config, port, and tunnel checks
+onboarder tunnel tailscale               # expose privately over the tailnet
+onboarder https check                    # DNS, ports 80/443, and Caddy readiness
+onboarder https setup                    # write/validate Caddyfile, obtain TLS, reload/start Caddy
+onboarder https status                   # domain, URL, Caddyfile, and Caddy state
+onboarder doctor                         # config, access key, ports, DNS, TLS, and tunnels
 ```
 
-Cloudflare quick tunnels and Tailscale are supported as reachability layers — the server keeps its loopback bind and the tunnel dials `127.0.0.1`. `ONBOARDER_CONFIG=/path/config.json` overrides the config location (handy for tests and containers).
+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.
+
+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:
+
+```bash
+sudo apt update
+sudo apt install caddy
+sudo ufw allow 80/tcp
+sudo ufw allow 443/tcp
+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.
+
+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.
+
+Cloudflare quick tunnels and Tailscale remain supported. They terminate TLS and dial `127.0.0.1`, so an existing loopback setup is preserved. `ONBOARDER_CONFIG=/path/config.json` overrides the config location for tests and containers.
 
 ---
 
@@ -228,9 +253,11 @@ 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
 │   ├── apiSettings.js# GET/PUT /api/settings, key rotation
 │   ├── tunnel.js    # Cloudflare & Tailscale status/commands
+│   ├── https.js     # Caddy config, ACME/TLS readiness & lifecycle
 │   ├── httpGuards.js# Host verification & CSRF/rebinding guards
 │   ├── apiScan.js   # Local & remote scan coordination
 │   ├── apiFile.js   # Path-traversal safe file serving
@@ -243,7 +270,7 @@ codebase-onboarder/
 │   ├── js/          # Vanilla ES modules (State, Inspector, Views, Settings)
 │   ├── vendor/      # Vendored Mermaid & Monaco Editor (Offline)
 │   └── index.html   # Main application interface
-└── tests/           # Comprehensive node:test suite (546 unit tests)
+└── tests/           # Comprehensive node:test suite (560 unit tests)
 ```
 
 ---
@@ -253,7 +280,7 @@ codebase-onboarder/
 Onboarder includes a comprehensive automated test suite built with Node's native test runner:
 
 ```bash
-# Run all 546 tests
+# Run all 560 tests
 npm test
 ```
 

package/cli/commands.js

@@ -15,9 +15,11 @@ import {
   publicSettings, serverUrls, maskAccessKey,
 } from '../server/config.js';
 import { startServer } from '../server/index.js';
+import { pidIsAlive, readPidFile, removePidFile } from '../server/pidfile.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 { buildSteps, pendingSteps, defaultOf, applyFlags, answersToSettings, summaryLines } from './wizard.js';
+import { buildSteps, unansweredSteps, defaultOf, applyFlags, answersToSettings, summaryLines } from './wizard.js';
 import { runSteps, WizardCancelled } from './prompt.js';
 
 // ---------------------------------------------------------------- setup ---
@@ -48,7 +50,7 @@ export async function runSetup({ flags = {}, out = console.log, err = console.er
 
   // Flag answers go in first; the wizard only asks what is left.
   const seed = {};
-  for (const id of ['name', 'email', 'mode', 'host', 'port', 'domain', 'autoOpen']) {
+  for (const id of ['name', 'email', 'mode', 'host', 'port', 'domain', 'https', 'autoOpen']) {
     if (flags[id] !== undefined) seed[id] = flags[id];
   }
   if (flags.provider !== undefined) seed.provider = flags.provider;
@@ -57,7 +59,7 @@ export async function runSetup({ flags = {}, out = console.log, err = console.er
 
   let answers;
   try {
-    answers = await runSteps(pendingSteps(buildSteps(current), seed), seed);
+    answers = await runSteps(unansweredSteps(buildSteps(current), seed), seed);
   } catch (e) {
     if (e instanceof WizardCancelled) {
       err('\n  Setup cancelled — nothing was written.');
@@ -97,7 +99,9 @@ export async function runSetup({ flags = {}, out = console.log, err = console.er
     out('');
     return runStart({ flags, out, err });
   }
-  out(dim('  Later: `onboarder start`'));
+  out(dim(settings.https
+    ? '  Later: `onboarder start` (starts Caddy automatically), or `onboarder https status`'
+    : '  Later: `onboarder start`'));
   return 0;
 }
 
@@ -153,11 +157,121 @@ export async function runStart({ flags = {}, out = console.log, err = console.er
     }
     out(dim(`  No config at ${file} — starting with defaults (local mode).`));
   }
-  const { server, host, port } = await startServer({ configFile: file, log: out });
-  if (flags.json) out(JSON.stringify({ host, port, url: `http://127.0.0.1:${port}/` }));
+  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 started = await startServer({ configFile: file, log: out });
+  if (started.settings.https) {
+    out('');
+    const httpsCode = await runHttps('setup', { flags, out: flags.json ? () => {} : out, err });
+    if (httpsCode !== 0) {
+      await new Promise((resolve) => started.server.close(resolve));
+      return httpsCode;
+    }
+  }
+  if (flags.json) out(JSON.stringify({ host: started.host, port: started.port, url: serverUrls(started.settings).local }));
   // The listening server holds the event loop; resolve so callers/tests know
   // we are up, but leave the process running.
-  return { server, host, port, code: 0 };
+  return { ...started, code: 0 };
+}
+
+// ------------------------------------------------------------- lifecycle ---
+
+export async function runStatus({ flags = {}, out = console.log } = {}) {
+  const file = flags.config || configPath();
+  const pid = readPidFile(file);
+  let running = pid && pidIsAlive(pid);
+  let settings = null;
+  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);
+  const result = {
+    running: Boolean(running || portBusy),
+    pid: running ? pid : null,
+    port: settings ? `${settings.host}:${settings.port}` : null,
+    portBusy,
+    managed: Boolean(running),
+    configFile: file,
+  };
+  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.'));
+  }
+  return 0;
+}
+
+function waitForExit(pid, timeoutMs = 5000) {
+  return new Promise((resolve) => {
+    const started = Date.now();
+    const poll = () => {
+      if (!pidIsAlive(pid)) return resolve(true);
+      if (Date.now() - started >= timeoutMs) return resolve(false);
+      setTimeout(poll, 100);
+    };
+    poll();
+  });
+}
+
+export async function runStop({ flags = {}, out = console.log, err = console.error } = {}) {
+  const file = flags.config || configPath();
+  const pid = readPidFile(file);
+  if (!pid) {
+    const settings = await readSettings(file);
+    const portBusy = !(await portIsFree(settings.host, settings.port));
+    if (flags.json) out(JSON.stringify({ stopped: false, reason: portBusy ? 'unmanaged busy port' : 'not running', port: `${settings.host}:${settings.port}` }, null, 2));
+    else if (portBusy) {
+      out(`${warn('!')}Port busy  ${settings.host}:${settings.port} — no Onboarder process record.`);
+      out(dim('    Inspect it with `ss -ltnp` or `lsof -i :' + settings.port + '`; `onboarder stop` will not kill an unmanaged process.'));
+    } else {
+      out(`${dash}Not running.`);
+    }
+    return portBusy ? 1 : 0;
+  }
+  if (!pidIsAlive(pid)) {
+    removePidFile(file, pid);
+    if (flags.json) out(JSON.stringify({ stopped: true, pid, stale: true }, null, 2));
+    else out(tick + `Removed stale process record for PID ${pid}.`);
+    return 0;
+  }
+  try {
+    process.kill(pid, 'SIGTERM');
+  } catch (error) {
+    if (error?.code !== 'ESRCH') throw error;
+  }
+  const stopped = await waitForExit(pid);
+  if (!stopped && pidIsAlive(pid)) {
+    err(`  PID ${pid} did not stop after SIGTERM.`);
+    err(dim('    Check it with `ps -p ' + pid + ' -f`, then stop it only if it really is Onboarder.'));
+    return 1;
+  }
+  removePidFile(file, pid);
+  if (flags.json) out(JSON.stringify({ stopped: true, pid }, null, 2));
+  else out(tick + `Stopped Onboarder (PID ${pid}).`);
+  return 0;
+}
+
+export async function runRestart(options = {}) {
+  const file = options.flags?.config || configPath();
+  const pid = readPidFile(file);
+  if (pid && pidIsAlive(pid)) {
+    const stopped = await runStop(options);
+    if (stopped !== 0) return stopped;
+  } else if (pid) {
+    removePidFile(file, pid);
+  }
+  return runStart(options);
 }
 
 // --------------------------------------------------------------- config ---
@@ -169,6 +283,7 @@ const SETTABLE = {
   host: (v) => v,
   port: (v) => { const n = Number(v); if (!Number.isInteger(n) || n < 1 || n > 65535) throw new Error('port must be 1-65535.'); return n; },
   domain: (v) => v,
+  https: (v) => ['true', 'yes', '1', 'on'].includes(String(v).toLowerCase()),
   autoOpen: (v) => ['true', 'yes', '1', 'on'].includes(String(v).toLowerCase()),
   'account.name': (v) => v,
   'account.email': (v) => v,
@@ -210,6 +325,7 @@ export async function runConfig(sub, args, { flags = {}, out = console.log } = {
       out(kv('Mode', settings.mode));
       out(kv('Bind', `${settings.host}:${settings.port}`));
       if (settings.domain) out(kv('Domain', settings.domain));
+      out(kv('HTTPS', settings.https ? `enabled — ${urls.domain}` : settings.domain ? 'disabled (plain HTTP)' : 'no domain configured'));
       out(kv('Local', urls.local));
       if (urls.network) out(kv('Network', urls.network));
       if (urls.domain) out(kv('Public', urls.domain));
@@ -341,17 +457,27 @@ export async function runDoctor({ flags = {}, out = console.log } = {}) {
       });
       const loopback = ['127.0.0.1', 'localhost', '::1', '[::1]'].includes(settings.host);
       checks.push({
-        id: 'domain', ok: loopback || Boolean(settings.domain), required: !loopback,
-        detail: settings.domain || (loopback ? '(none — a tunnel provides the name)' : 'MISSING — a LAN bind needs a domain'),
+        id: 'domain', ok: true, required: false,
+        detail: settings.domain || (loopback ? '(none — a tunnel or local reverse proxy provides the name)' : '(none — visitors can connect by server IP)'),
       });
+      if (settings.https) {
+        const readiness = await httpsReadiness(settings, { configFile: file });
+        for (const check of readiness.checks.slice(1).filter((item) => item.id !== 'caddy')) {
+          checks.push({ ...check, required: check.id !== 'dns-target' });
+        }
+      }
     }
   }
 
-  for (const name of ['git', 'cloudflared', 'tailscale']) {
-    const wanted = name === 'git' || (settings && settings.tunnel?.[name === 'cloudflared' ? 'cloudflare' : 'tailscale']);
+  for (const name of ['git', 'cloudflared', 'tailscale', 'caddy']) {
+    const wanted = name === 'git'
+      || (name === 'caddy' && settings?.https)
+      || (settings && settings.tunnel?.[name === 'cloudflared' ? 'cloudflare' : 'tailscale']);
     const found = Boolean(findOnPath(name));
     checks.push({
-      id: name, ok: found || !wanted, required: name === 'git',
+      id: name,
+      ok: found || !wanted,
+      required: name === 'git' || (name === 'caddy' && settings?.https),
       detail: found ? 'installed' : wanted ? 'not installed — ' + installHint(name) : 'not installed (not needed for your settings)',
     });
   }
@@ -378,6 +504,92 @@ function portIsFree(host, port) {
   });
 }
 
+// ------------------------------------------------------------------ https ---
+
+export async function runHttps(action = 'status', { flags = {}, out = console.log, err = console.error } = {}) {
+  const file = flags.config || configPath();
+  const settings = await readSettings(file);
+  const status = httpsStatus(settings, file);
+  if (action === 'status') {
+    if (flags.json) out(JSON.stringify(status, null, 2));
+    else {
+      out('');
+      out(bold('  Onboarder HTTPS'));
+      out(kv('Enabled', status.enabled ? 'yes' : 'no'));
+      out(kv('Domain', status.domain || '(not configured)'));
+      out(kv('URL', status.url || '(none)'));
+      out(kv('Caddy', status.caddyInstalled ? status.caddyVersion : 'not installed'));
+      out(kv('Caddyfile', status.caddyfile));
+      if (status.enabled) out(dim('    `onboarder https check` verifies DNS and ports before issuance.'));
+      out('');
+    }
+    return status.enabled ? 0 : 1;
+  }
+  if (action === 'check') {
+    const readiness = await httpsReadiness(settings, { configFile: file });
+    if (flags.json) out(JSON.stringify(readiness, null, 2));
+    else {
+      out('');
+      out(bold('  HTTPS readiness'));
+      for (const check of readiness.checks) out(`${check.ok ? tick : check.required ? cross : dash}${check.id} — ${check.detail}`);
+      if (!readiness.ok) {
+        out('');
+        out(warn('  Fix the required items, then run `onboarder https setup` again.'));
+        out(dim('    DNS: point an A/AAAA record to this VPS. Firewall: allow inbound 80 and 443.'));
+      }
+      out('');
+    }
+    return readiness.ok ? 0 : 1;
+  }
+  if (action === 'setup' || action === 'start') {
+    const readiness = await httpsReadiness(settings, { configFile: file });
+    if (!readiness.ok) {
+      err(bad('  HTTPS setup is not ready:'));
+      for (const check of readiness.checks.filter((item) => item.required && !item.ok)) err(cross + check.id + ' — ' + check.detail);
+      err('    Point DNS at this VPS, allow inbound TCP 80/443, install Caddy, then retry.');
+      return 1;
+    }
+    const caddyfile = await writeCaddyfile(settings, file);
+    out(dim('  Caddyfile: ' + caddyfile));
+    await caddyValidate(settings, file);
+
+    // Ubuntu's package usually leaves Caddy running as a service. Reload first
+    // so repeat setup is idempotent and does not mistake Caddy for a foreign
+    // listener. Reload talks only to Caddy's local admin endpoint and never
+    // stops an unknown process.
+    let result;
+    let reloaded = false;
+    try {
+      result = caddyRun(settings, file, 'reload');
+      reloaded = true;
+    } catch {
+      try {
+        result = caddyRun(settings, file, 'start');
+      } catch (error) {
+        err(bad('  Caddy could not start: ' + (error.message || error)));
+        if (process.platform !== 'win32') {
+          err('    On Ubuntu, start the packaged service once:');
+          err('      sudo systemctl enable --now caddy');
+          err('    Then run `onboarder https setup` again.');
+        }
+        return 1;
+      }
+    }
+    out(tick + (reloaded ? 'Caddy reloaded. It is using' : 'Caddy started. It is using') + ' https://' + settings.domain + '.');
+    out('    Public URL  https://' + settings.domain);
+    out(dim('    Upstream     http://127.0.0.1:' + settings.port));
+    if (result.output) out(dim('    ' + result.output.split('\n').slice(-3).join('\n    ')));
+    return 0;
+  }
+  if (action === 'stop') {
+    if (!status.caddyInstalled) { err('  Caddy is not installed.'); return 1; }
+    caddyRun(settings, file, 'stop');
+    out(tick + 'Caddy stopped. The Onboarder HTTP server is unchanged.');
+    return 0;
+  }
+  throw new Error('Usage: onboarder https <check|setup|start|stop|status>');
+}
+
 // --------------------------------------------------------------- tunnel ---
 
 export async function runTunnel(kind, { flags = {}, out = console.log, err = console.error } = {}) {
@@ -433,4 +645,3 @@ export async function runTunnel(kind, { flags = {}, out = console.log, err = con
   }
   throw new Error('Usage: onboarder tunnel <cloudflare|tailscale>');
 }
-

package/cli/main.js

@@ -7,7 +7,10 @@
 import fs from 'node:fs';
 import { parseArgs } from 'node:util';
 
-import { runSetup, runStart, runConfig, runConfigKey, runConfigReset, runDoctor, runTunnel } from './commands.js';
+import {
+  runSetup, runStart, runStatus, runStop, runRestart,
+  runConfig, runConfigKey, runConfigReset, runDoctor, runTunnel, runHttps,
+} from './commands.js';
 
 const PACKAGE = JSON.parse(fs.readFileSync(new URL('../package.json', import.meta.url), 'utf8'));
 
@@ -18,12 +21,17 @@ const HELP = `
     onboarder                     Start the server (runs setup first if needed)
     onboarder setup | onboard     Configure interactively (the wizard)
     onboarder start               Start the server
-    onboarder config <…>          show | get <key> | set <key> <value> | path | reset | key <rotate|show|set>
+    onboarder status              Show whether the server is running
+    onboarder stop                Stop the running server
+    onboarder restart             Stop and start again
+    onboarder config [<…>]         show | get <key> | set <key> <value> | path | reset | key <rotate|show|set>
     onboarder tunnel <name>       cloudflare | tailscale
+    onboarder https <action>      check | setup | start | stop | status
     onboarder doctor              Check the machine and the config
 
   Setup flags (interactive wizard skips what they answer)
     --mode local|self-hosted   --host <addr>   --port <n>   --domain <name>
+    --https                    Set up automatic HTTPS through Caddy
     --access-key generate|<k>  --name <n>   --email <e>
     --provider none|openai-compatible|ollama|openrouter|custom
     --base-url <url>   --model <m>   --cloudflare   --tailscale
@@ -37,10 +45,15 @@ const HELP = `
     --no-color          Plain output (NO_COLOR works too)
     -h, --help          This text      -v, --version      Print the version
 
+  Also accepted
+    help | --help       onboarder help | onboarder --help
+    config | config show
+
   Examples
     onboarder setup
     onboarder setup --non-interactive --mode local --port 4310
-    onboarder setup --non-interactive --mode self-hosted --domain map.example.com --access-key generate
+    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
 `;
 
@@ -59,6 +72,7 @@ const OPTIONS = {
   host: { type: 'string' },
   port: { type: 'string' },
   domain: { type: 'string' },
+  https: { type: 'boolean' },
   'access-key': { type: 'string' },
   name: { type: 'string' },
   email: { type: 'string' },
@@ -97,9 +111,18 @@ export async function main(argv = process.argv.slice(2)) {
   const [cmd, sub, ...rest] = positionals;
   try {
     switch (cmd) {
+      case 'help':
+        console.log(HELP);
+        return 0;
       case undefined:
       case 'start':
         return codeOf(await runStart({ flags }));
+      case 'status':
+        return codeOf(await runStatus({ flags }));
+      case 'stop':
+        return codeOf(await runStop({ flags }));
+      case 'restart':
+        return codeOf(await runRestart({ flags }));
       case 'setup':
       case 'onboard':
       case 'init':
@@ -107,9 +130,11 @@ export async function main(argv = process.argv.slice(2)) {
       case 'config':
         if (sub === 'key') return codeOf(await runConfigKey(rest[0], rest.slice(1), { flags }));
         if (sub === 'reset') return codeOf(await runConfigReset({ flags }));
-        return codeOf(await runConfig(sub, rest, { flags }));
+        return codeOf(await runConfig(sub || 'show', rest, { flags }));
       case 'tunnel':
         return codeOf(await runTunnel(sub, { flags }));
+      case 'https':
+        return codeOf(await runHttps(sub || 'status', { flags }));
       case 'doctor':
         return codeOf(await runDoctor({ flags }));
       default:

package/cli/prompt.js

@@ -32,6 +32,11 @@ export async function runSteps(steps, answers = {}, io = {}) {
   try {
     let lastSection = null;
     for (const step of steps) {
+      // `when` is evaluated here, one question at a time — never upfront.
+      // Conditions read answers collected earlier in the same run ("ask about
+      // the bind only when mode is self-hosted"), so filtering the list
+      // before the first question would prune branches the answers reopen.
+      if (step.when && !step.when(answers)) continue;
       if (step.section && step.section !== lastSection) {
         output.write(section(step.section) + '\n');
         lastSection = step.section;

package/cli/wizard.js

@@ -12,7 +12,7 @@
 
 import os from 'node:os';
 
-import { DEFAULT_SETTINGS, generateAccessKey, normalizeSettings } from '../server/config.js';
+import { DEFAULT_SETTINGS, generateAccessKey, isLoopbackHost, normalizeSettings } from '../server/config.js';
 
 // Provider presets for the AI account step. `none` is the honest default: the
 // app works fully offline, and the browser can still hold its own key.
@@ -99,10 +99,15 @@ export function buildSteps(current = DEFAULT_SETTINGS) {
       id: 'host', section: 'Server', type: 'choice',
       question: 'What should the server bind to?',
       choices: [
-        { value: '127.0.0.1', label: 'Loopback, behind a tunnel (recommended)', hint: 'Cloudflare or Tailscale terminates TLS and dials 127.0.0.1' },
-        { value: '0.0.0.0', label: 'Every interface (LAN)', hint: 'other machines on this network reach it directly — plain HTTP, so front it with a domain + proxy for TLS' },
+        { value: '127.0.0.1', label: 'Loopback only — behind Cloudflare or Tailscale', hint: 'safest remote layout; the tunnel/proxy connects to 127.0.0.1' },
+        { value: '0.0.0.0', label: 'Every interface — direct public/LAN access', hint: 'accessible by server IP; recommended for a cloud VPS' },
       ],
-      default: current.host === '0.0.0.0' ? '0.0.0.0' : '127.0.0.1',
+      default: (answers) => {
+        const currentHost = current.host;
+        if (answers.host) return answers.host;
+        if (current.mode === 'self-hosted' && ['127.0.0.1', 'localhost', '::1', '[::1]'].includes(currentHost)) return currentHost;
+        return '0.0.0.0';
+      },
       when: (a) => a.mode === 'self-hosted',
     },
     {
@@ -113,12 +118,19 @@ export function buildSteps(current = DEFAULT_SETTINGS) {
     },
     {
       id: 'domain', section: 'Server', type: 'text',
-      question: 'Domain (optional behind a tunnel)',
-      hint: 'e.g. map.example.com — required for a direct LAN bind, optional when a tunnel provides the name',
+      question: 'Domain (optional for direct IP or a tunnel)',
+      hint: 'e.g. map.example.com — point an A/AAAA record to this VPS to enable trusted HTTPS',
       default: current.domain || '',
       validate: validDomain,
       when: (a) => a.mode === 'self-hosted',
     },
+    {
+      id: 'https', section: 'HTTPS', type: 'confirm',
+      question: 'Set up automatic HTTPS with Caddy?',
+      hint: 'Caddy obtains and renews the certificate, proxies 80/443, and sends traffic to this app',
+      default: Boolean(current.domain && current.https),
+      when: (a) => a.mode === 'self-hosted' && Boolean(a.domain),
+    },
     {
       id: 'keyChoice', section: 'Security', type: 'choice',
       question: 'Access key — the one credential remote devices must hold',
@@ -190,6 +202,16 @@ export function pendingSteps(steps, answers = {}) {
   return steps.filter((s) => !(s.id in answers) && (!s.when || s.when(answers)));
 }
 
+// Steps the flags did not answer, in order — and nothing more. Unlike
+// `pendingSteps` this never looks at `when`: conditions read answers that
+// only exist mid-run ("ask about the bind once mode is self-hosted"), so
+// evaluating them before the first question prunes branches the typed answers
+// would reopen. The renderer (`prompt.js#runSteps`) evaluates `when` live,
+// one question at a time, which is the only moment it can be answered truly.
+export function unansweredSteps(steps, answers = {}) {
+  return steps.filter((s) => !(s.id in answers));
+}
+
 // Defaults may depend on earlier answers (`default` as a function).
 export function defaultOf(step, answers) {
   return typeof step.default === 'function' ? step.default(answers) : step.default;
@@ -221,9 +243,10 @@ export function answersToSettings(current, answers) {
   return normalizeSettings({
     version: current.version,
     mode: selfHosted ? 'self-hosted' : 'local',
-    host: selfHosted ? (answers.host || current.host || '127.0.0.1') : '127.0.0.1',
+    host: selfHosted ? (answers.host || '0.0.0.0') : '127.0.0.1',
     port: Number(answers.port ?? current.port ?? DEFAULT_SETTINGS.port),
     domain: selfHosted ? String(answers.domain ?? current.domain ?? '').trim().toLowerCase() : '',
+    https: selfHosted && Boolean(answers.domain) && Boolean(answers.https),
     accessKey,
     autoOpen: answers.autoOpen ?? current.autoOpen ?? false,
     account,
@@ -255,6 +278,7 @@ export function applyFlags(current, flags = {}) {
     if (err) throw new Error('--domain: ' + err);
     patch.domain = String(flags.domain).trim().toLowerCase();
   }
+  if (flags.https !== undefined) patch.https = Boolean(flags.https);
   if (flags.accessKey === 'generate') patch.accessKey = generateAccessKey();
   else if (flags.accessKey !== undefined) {
     if (String(flags.accessKey).trim().length < 16) throw new Error('--access-key must be at least 16 characters, or "generate".');
@@ -290,11 +314,15 @@ export function applyFlags(current, flags = {}) {
     account: { ...(current.account || DEFAULT_SETTINGS.account), ...account },
     tunnel: { ...(current.tunnel || DEFAULT_SETTINGS.tunnel), ...tunnel },
   };
-  // Mode drove host/domain rules inside normalize; when flags move a config to
-  // local mode the network fields have to come along rather than linger.
+  // A fresh self-hosted setup is direct-first for cloud/VPS use. Re-running setup
+  // preserves an existing deliberate loopback choice for tunnels and Caddy.
+  if (flags.mode === 'self-hosted' && flags.host === undefined && current.mode !== 'self-hosted') {
+    merged.host = '0.0.0.0';
+  }
   if (merged.mode === 'local') {
     if (!['127.0.0.1', 'localhost', '::1', '[::1]'].includes(merged.host)) merged.host = '127.0.0.1';
     if (flags.domain === undefined) merged.domain = '';
+    if (flags.https === undefined) merged.https = false;
   }
   return { patch, settings: normalizeSettings(merged) };
 }
@@ -306,11 +334,14 @@ export function summaryLines(settings, { revealKey = false } = {}) {
     ['Mode', settings.mode],
     ['Bind', `${settings.host}:${settings.port}`],
   ];
-  if (settings.domain) lines.push(['Domain', 'https://' + settings.domain]);
+  if (settings.domain) lines.push(['Domain', (settings.https ? 'https://' : 'http://') + settings.domain + (settings.https ? '' : ':' + settings.port)]);
   if (settings.mode === 'self-hosted') {
     lines.push(['Access key', revealKey
       ? settings.accessKey
       : (settings.accessKey ? settings.accessKey.slice(0, 6) + '… (hidden)' : '(none — the API will refuse every call)')]);
+    if (isLoopbackHost(settings.host)) {
+      lines.push(['Network', 'loopback only — use a tunnel or bind 0.0.0.0 for direct access']);
+    }
   }
   const who = [settings.account.name, settings.account.email].filter(Boolean).join(' · ');
   if (who) lines.push(['Profile', who]);
@@ -322,4 +353,3 @@ export function summaryLines(settings, { revealKey = false } = {}) {
   lines.push(['Auto-open', settings.autoOpen ? 'yes' : 'no']);
   return lines;
 }
-

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "codebase-onboarder",
-  "version": "0.1.0",
+  "version": "0.3.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

@@ -389,9 +389,16 @@
     </label>
   </div>
   <label class="field" id="srvDomainField">
-    <span class="field-label">Domain (optional for LAN, required for a public name)</span>
+    <span class="field-label">Domain (optional for direct IP or a tunnel)</span>
     <input type="text" id="srvDomain" class="text-input" placeholder="map.example.com" spellcheck="false">
   </label>
+  <div id="srvHttpsField" hidden>
+    <label class="check-row">
+      <input type="checkbox" id="srvHttps">
+      <span>Automatic HTTPS with Caddy</span>
+    </label>
+    <p class="drawer-fine" id="srvHttpsStatus"></p>
+  </div>
   <label class="check-row">
     <input type="checkbox" id="srvAutoOpen">
     <span>Open the browser when the server starts</span>

package/public/js/api.js

@@ -261,4 +261,3 @@ export async function updateServerSettings(patch) {
 export function rotateServerAccessKey() {
   return postJSON('/api/settings/access-key', {});
 }
-

package/public/js/serverSettings.js

@@ -29,7 +29,7 @@ export function createServerDrawer(options = {}) {
   const dom = {};
   [
     'serverDrawer', 'serverScrim', 'serverClose', 'serverModeNote', 'srvMode', 'srvHost', 'srvPort',
-    'srvDomain', 'srvDomainField', 'srvAutoOpen', 'srvKeySection', 'srvKeyMasked', 'srvRotate',
+    'srvDomain', 'srvDomainField', 'srvHttps', 'srvHttpsField', 'srvHttpsStatus', 'srvAutoOpen', 'srvKeySection', 'srvKeyMasked', 'srvRotate',
     'srvFreshKeyRow', 'srvFreshKey', 'srvCopyKey', 'srvKeyHint', 'srvName', 'srvEmail',
     'srvTunnelCloudflare', 'srvTunnelCloudflareStatus', 'srvTunnelTailscale', 'srvTunnelTailscaleStatus',
     'srvSave', 'srvStatus', 'srvConfigPath',
@@ -61,6 +61,10 @@ export function createServerDrawer(options = {}) {
     dom.srvHost.value = s.host;
     dom.srvPort.value = s.port;
     dom.srvDomain.value = s.domain || '';
+    dom.srvHttps.checked = Boolean(s.https);
+    dom.srvHttpsStatus.textContent = data.https?.caddyInstalled
+      ? `Caddy ${data.https.caddyVersion || 'installed'}. ${s.https ? 'Run `onboarder https setup` after saving.' : 'Enable HTTPS above, save, then run the command.'}`
+      : 'Caddy is not installed. Ubuntu: sudo apt install caddy; macOS: brew install caddy.';
     dom.srvAutoOpen.checked = Boolean(s.autoOpen);
     dom.srvName.value = s.account?.name || '';
     dom.srvEmail.value = s.account?.email || '';
@@ -82,6 +86,7 @@ export function createServerDrawer(options = {}) {
     const remote = dom.srvMode.value === 'self-hosted';
     dom.srvKeySection.hidden = !remote;
     dom.srvDomainField.hidden = !remote;
+    dom.srvHttpsField.hidden = !remote || !dom.srvDomain.value.trim();
     dom.serverModeNote.textContent = MODE_NOTES[dom.srvMode.value] || '';
   }
 
@@ -113,16 +118,22 @@ export function createServerDrawer(options = {}) {
       account: { name: dom.srvName.value.trim(), email: dom.srvEmail.value.trim() },
       tunnel: { cloudflare: dom.srvTunnelCloudflare.checked, tailscale: dom.srvTunnelTailscale.checked },
     };
-    if (patch.mode === 'self-hosted') patch.domain = dom.srvDomain.value.trim();
+    if (patch.mode === 'self-hosted') {
+      patch.domain = dom.srvDomain.value.trim();
+      patch.https = dom.srvHttps.checked;
+    }
     status('Saving…');
     try {
       const data = await updateServerSettings(patch);
       render({ ...current, settings: data.settings });
       const restart = (data.restartRequired || []).join(' and ');
+      const httpsChanged = (data.restartRequired || []).some((key) => key === 'domain' || key === 'https');
       status(
-        restart
-          ? `Saved. The ${restart} change takes effect after a restart — the running socket cannot move.`
-          : 'Saved — live already.',
+        httpsChanged
+          ? 'Saved. Run `onboarder https setup` to validate the Caddyfile and reload TLS.'
+          : restart
+            ? `Saved. The ${restart} change takes effect after a restart — the running socket cannot move.`
+            : 'Saved — live already.',
         'ok',
       );
     } catch (err) {
@@ -147,6 +158,7 @@ export function createServerDrawer(options = {}) {
   }
 
   dom.srvMode.addEventListener('change', applyModeVisibility);
+  dom.srvDomain.addEventListener('input', applyModeVisibility);
   dom.srvSave.addEventListener('click', save);
   dom.srvRotate.addEventListener('click', rotate);
   dom.serverClose.addEventListener('click', close);
@@ -166,4 +178,3 @@ export function createServerDrawer(options = {}) {
     isOpen: () => !dom.serverDrawer.hidden,
   };
 }
-

package/server/apiSettings.js

@@ -13,6 +13,7 @@ import {
 } from './config.js';
 import { sendError, sendJSON } from './http.js';
 import { tunnelStatus } from './tunnel.js';
+import { httpsStatus } from './https.js';
 
 // Where this request's settings live. The router's config object carries the
 // path when the server was booted with one; tests and a bare `createServer()`
@@ -37,6 +38,7 @@ async function publicBody(config) {
     configFile: settingsFile(config) || configPath(),
     node: process.version,
     tunnels: tunnelStatus(settings),
+    https: httpsStatus(settings, settingsFile(config) || configPath()),
   };
 }
 
@@ -48,15 +50,17 @@ export async function handleGetSettings(req, res, config) {
   }
 }
 
-// Which changes the running server cannot absorb. Auth, domain, and tunnel
-// flags are read live from disk on each request; the bind is a socket that
-// already exists.
+// Which changes the running server cannot absorb. Access-key and tunnel flags
+// are read live per request. Host/port are bound sockets. Domain/HTTPS change
+// the managed Caddyfile and certificate, so Caddy must validate/reload too.
 function restartRequired(config, next) {
   const boot = config?.boot;
   if (!boot) return [];
   const changed = [];
   if (next.host !== boot.host) changed.push('host');
   if (next.port !== boot.port) changed.push('port');
+  if (next.domain !== boot.domain) changed.push('domain');
+  if (next.https !== boot.https) changed.push('https');
   return changed;
 }
 
@@ -70,7 +74,7 @@ export async function handleUpdateSettings(res, body, config) {
   }
   // Only known keys may be patched — a typo like "ports" must be a loud 400,
   // not a silently ignored write that the UI then claims it saved.
-  const allowed = new Set(['mode', 'host', 'port', 'domain', 'autoOpen', 'account', 'tunnel']);
+  const allowed = new Set(['mode', 'host', 'port', 'domain', 'https', 'autoOpen', 'account', 'tunnel']);
   const unknown = Object.keys(body).filter((k) => k !== 'accessKey' && !allowed.has(k));
   if (unknown.length) {
     return sendError(res, 400, `Unknown setting${unknown.length === 1 ? '' : 's'}: ${unknown.join(', ')}.`);

package/server/config.js

@@ -7,7 +7,7 @@ import { randomBytes, timingSafeEqual } from 'node:crypto';
 import os from 'node:os';
 import path from 'node:path';
 
-export const CONFIG_VERSION = 1;
+export const CONFIG_VERSION = 2;
 export const LOOPBACK_HOSTS = new Set(['127.0.0.1', 'localhost', '::1', '[::1]']);
 export const DEFAULT_SETTINGS = Object.freeze({
   version: CONFIG_VERSION,
@@ -15,6 +15,10 @@ export const DEFAULT_SETTINGS = Object.freeze({
   host: '127.0.0.1',
   port: 4310,
   domain: '',
+  // When a domain is configured, ask Caddy to obtain and renew a trusted TLS
+  // certificate and reverse-proxy this app. The certificate itself belongs to
+  // Caddy; the server still speaks plain HTTP to its local upstream.
+  https: false,
   accessKey: '',
   // Whether `onboarder start` opens the app in a browser once it is listening.
   // Off in the schema so `npm start` from a checkout stays quiet; the setup
@@ -82,6 +86,7 @@ export function normalizeSettings(value = {}) {
     host,
     port: normalizePort(value.port ?? DEFAULT_SETTINGS.port),
     domain: normalizeDomain(value.domain),
+    https: Boolean(value.https),
     accessKey: cleanString(value.accessKey, 256),
     autoOpen: value.autoOpen === undefined ? DEFAULT_SETTINGS.autoOpen : Boolean(value.autoOpen),
     account: normalizeAccount(value.account),
@@ -91,9 +96,11 @@ export function normalizeSettings(value = {}) {
   if (settings.mode === 'local' && !isLoopbackHost(settings.host)) {
     throw new Error('Local mode only binds to 127.0.0.1, localhost, or ::1. Choose self-hosted mode for a network bind.');
   }
-  if (settings.mode === 'self-hosted' && !isLoopbackHost(settings.host) && !settings.domain) {
-    throw new Error('A self-hosted network bind needs a domain (or keep the server on loopback behind a tunnel).');
+  if (settings.https && !settings.domain) {
+    throw new Error('HTTPS needs a domain such as map.example.com. A public IP alone cannot be used for a normal trusted certificate.');
   }
+  // Self-hosted needs no domain: a bare-IP bind (a VPS with no DNS name) is a
+  // legitimate layout. Every API call needs the access key either way.
   return settings;
 }
 
@@ -112,7 +119,7 @@ export function serverUrls(value = DEFAULT_SETTINGS) {
       ? `http://<this-machine>:${settings.port} (every interface)`
       : `http://${settings.host}:${settings.port}`;
   }
-  if (settings.domain) urls.domain = `https://${settings.domain}`;
+  if (settings.domain) urls.domain = settings.https ? `https://${settings.domain}` : `http://${settings.domain}:${settings.port}`;
   return urls;
 }
 
@@ -123,6 +130,12 @@ export function maskAccessKey(key) {
   return `${value.slice(0, 6)}…${value.slice(-4)}`;
 }
 
+export function browserUrl(settings) {
+  const url = new URL(serverUrls(settings).local);
+  if (settings.mode === 'self-hosted' && settings.accessKey) url.searchParams.set('key', settings.accessKey);
+  return url.toString();
+}
+
 export function publicSettings(value = DEFAULT_SETTINGS) {
   const settings = normalizeSettings(value);
   return {
@@ -131,6 +144,7 @@ export function publicSettings(value = DEFAULT_SETTINGS) {
     host: settings.host,
     port: settings.port,
     domain: settings.domain,
+    https: settings.https,
     autoOpen: settings.autoOpen,
     hasAccessKey: Boolean(settings.accessKey),
     accessKeyMasked: maskAccessKey(settings.accessKey),
@@ -154,11 +168,41 @@ export function publicSettings(value = DEFAULT_SETTINGS) {
 // safe because it can only widen Host acceptance in self-hosted mode, where
 // every API call already needs the access key — the guard's job there is
 // keeping drive-by traffic off the static files, not authentication.
+// A wildcard bind (0.0.0.0 / ::) has no name of its own, so the names it
+// honestly answers to are this machine's own interface addresses — a request
+// addressed to 10.0.0.2 or a public VPS IP really did arrive here. Read at
+// call time (the router asks per request), so a DHCP lease change does not
+// strand the guard on a stale address.
+function ownInterfaceHosts() {
+  const hosts = [];
+  for (const list of Object.values(os.networkInterfaces())) {
+    for (const addr of list || []) {
+      if (addr.internal) continue; // loopback is always allowed anyway
+      hosts.push(addr.address);
+    }
+  }
+  return hosts;
+}
+
 export function allowedHosts(value = DEFAULT_SETTINGS) {
   const settings = normalizeSettings(value);
   const hosts = new Set();
   if (settings.domain) hosts.add(settings.domain);
-  if (!isLoopbackHost(settings.host)) hosts.add(settings.host.toLowerCase());
+  if (!isLoopbackHost(settings.host)) {
+    // A wildcard bind is useful as a literal Host value to diagnostics, even
+    // though browsers normally address the machine by one of its real IPs.
+    hosts.add(settings.host.toLowerCase());
+    if (settings.host === '0.0.0.0') {
+      // A cloud VPS commonly reaches its public address through provider NAT,
+      // so that address is not present in os.networkInterfaces(). These markers
+      // let the guard accept an IP literal without accepting arbitrary domains.
+      hosts.add('ipv4:*');
+      for (const ip of ownInterfaceHosts()) if (!ip.includes(':')) hosts.add(ip);
+    } else if (settings.host === '::') {
+      hosts.add('ipv6:*');
+      for (const ip of ownInterfaceHosts()) if (ip.includes(':')) hosts.add(ip);
+    }
+  }
   if (settings.tunnel.cloudflare) hosts.add('*.trycloudflare.com');
   if (settings.tunnel.tailscale) hosts.add('*.ts.net');
   return [...hosts];

package/server/httpGuards.js

@@ -7,6 +7,8 @@
 // open from driving this server on their behalf. Binding to 127.0.0.1 keeps
 // the network out; it does nothing about the browser, which is already inside.
 
+import net from 'node:net';
+
 const LOOPBACK_HOSTS = new Set(['localhost', '127.0.0.1', '[::1]', '::1']);
 
 // "localhost:4310" -> "localhost", "[::1]:4310" -> "[::1]"
@@ -41,6 +43,8 @@ export function rebindingReason(req, extraHosts = []) {
   const name = hostnameOf(host);
   if (LOOPBACK_HOSTS.has(name)) return null;
   for (const extra of extraHosts) {
+    if (extra === 'ipv4:*' && net.isIP(name) === 4) return null;
+    if (extra === 'ipv6:*' && net.isIP(name.replace(/^\[|\]$/g, '')) === 6) return null;
     if (extra.startsWith('*.')) {
       // "*.trycloudflare.com" matches "abc.trycloudflare.com" but not the bare
       // suffix itself and not "evil-trycloudflare.com".

package/server/https.js

@@ -0,0 +1,142 @@
+import { promises as dns } from 'node:dns';
+import { promises as fs, statSync } from 'node:fs';
+import net from 'node:net';
+import os from 'node:os';
+import path from 'node:path';
+import { spawnSync } from 'node:child_process';
+
+import { configPath, normalizeSettings } from './config.js';
+import { findOnPath, installHint } from './tunnel.js';
+
+export function caddyfilePath(configFile = configPath()) {
+  return path.join(path.dirname(configFile), 'Caddyfile');
+}
+
+export function renderCaddyfile(settings) {
+  const s = normalizeSettings(settings);
+  if (!s.domain) throw new Error('HTTPS needs a domain. Run `onboarder setup` and enter one first.');
+  return `# Managed by Onboarder. Edits are replaced by \`onboarder https setup\`.\n${s.domain} {\n  reverse_proxy 127.0.0.1:${s.port}\n}\n`;
+}
+
+function portIsFree(port, host = '0.0.0.0') {
+  return new Promise((resolve) => {
+    const probe = net.createServer();
+    probe.once('error', () => resolve(false));
+    probe.listen(port, host, () => probe.close(() => resolve(true)));
+  });
+}
+
+async function resolveDomain(domain) {
+  const [v4, v6] = await Promise.allSettled([dns.resolve4(domain), dns.resolve6(domain)]);
+  const addresses = [
+    ...(v4.status === 'fulfilled' ? v4.value : []),
+    ...(v6.status === 'fulfilled' ? v6.value : []),
+  ];
+  return [...new Set(addresses)];
+}
+
+function localAddresses() {
+  const found = [];
+  for (const list of Object.values(os.networkInterfaces())) {
+    for (const address of list || []) if (!address.internal) found.push(address.address);
+  }
+  return found;
+}
+
+async function caddyIsRunning(probe = portIsFree) {
+  // If 80 and 443 are both occupied, probe Caddy's local admin endpoint. This
+  // distinguishes the Ubuntu service from an unknown listener without sudo.
+  if (await probe(80)) return false;
+  if (await probe(443)) return false;
+  return new Promise((resolve) => {
+    const socket = net.connect(2019, '127.0.0.1');
+    const finish = (value) => { socket.destroy(); resolve(value); };
+    socket.setTimeout(800, () => finish(false));
+    socket.once('connect', () => finish(true));
+    socket.once('error', () => finish(false));
+  });
+}
+
+export async function httpsReadiness(settings, { configFile = configPath(), resolve = resolveDomain, probe = portIsFree, tool = findOnPath, running = caddyIsRunning } = {}) {
+  const s = normalizeSettings(settings);
+  const caddy = tool('caddy');
+  const checks = [{ id: 'domain', ok: Boolean(s.domain), required: true, detail: s.domain || 'not configured' }];
+  if (!s.domain) return { ok: false, checks, caddy, addresses: [], local: [] };
+
+  let addresses = [];
+  let dnsError = '';
+  try { addresses = await resolve(s.domain); } catch (error) { dnsError = error.code || error.message; }
+  checks.push({ id: 'dns', ok: addresses.length > 0, required: true, detail: addresses.length ? addresses.join(', ') : `does not resolve${dnsError ? ` (${dnsError})` : ''}` });
+  const local = localAddresses();
+  const matches = addresses.some((address) => local.includes(address));
+  checks.push({ id: 'dns-target', ok: matches, required: false, detail: matches ? 'resolves to this machine' : 'does not match a local interface address (NAT/public-IP and proxy setups can still be valid)' });
+
+  const serviceRunning = await running(probe);
+  for (const port of [80, 443]) {
+    const free = await probe(port);
+    const ownedByCaddy = !free && serviceRunning;
+    checks.push({
+      id: `port-${port}`,
+      ok: free || ownedByCaddy,
+      required: true,
+      detail: free ? 'available for Caddy' : ownedByCaddy ? 'in use by the running Caddy service' : 'already in use — stop the existing web server or proxy',
+    });
+  }
+  checks.push({ id: 'caddy', ok: caddy.installed, required: true, detail: caddy.installed ? caddy.version : 'not installed — ' + installHint('caddy') });
+  return { ok: checks.every((check) => check.ok || !check.required), checks, caddy, addresses, local };
+}
+
+export function httpsStatus(settings, configFile = configPath()) {
+  const s = normalizeSettings(settings);
+  const file = caddyfilePath(configFile);
+  const caddy = findOnPath('caddy');
+  let configured = false;
+  try { configured = Boolean(statSync(file)); } catch { configured = false; }
+  return {
+    enabled: Boolean(s.domain && s.https),
+    domain: s.domain,
+    url: s.domain && s.https ? `https://${s.domain}` : '',
+    caddyfile: file,
+    caddyInstalled: caddy.installed,
+    caddyVersion: caddy.version || '',
+    configured,
+    command: s.domain && s.https ? `caddy start --config ${file}` : '',
+  };
+}
+
+export async function writeCaddyfile(settings, configFile = configPath()) {
+  const file = caddyfilePath(configFile);
+  await fs.mkdir(path.dirname(file), { recursive: true, mode: 0o700 });
+  await fs.writeFile(file, renderCaddyfile(settings), { encoding: 'utf8', mode: 0o600 });
+  return file;
+}
+
+export async function caddyValidate(settings, configFile = configPath()) {
+  const s = normalizeSettings(settings);
+  if (!s.domain) throw new Error('HTTPS needs a domain. Run `onboarder setup` and enter one first.');
+  const caddy = findOnPath('caddy');
+  if (!caddy.installed) throw new Error('Caddy is not installed. ' + installHint('caddy'));
+  const file = caddyfilePath(configFile);
+  const result = spawnSync('caddy', ['validate', '--config', file], { encoding: 'utf8' });
+  if (result.error) throw result.error;
+  if (result.status !== 0) throw new Error(String(result.stderr || result.stdout || 'Caddy configuration is invalid.').trim());
+  return { file, output: String(result.stdout || result.stderr || '').trim() };
+}
+
+export function caddyRun(settings, configFile = configPath(), action = 'start') {
+  const s = normalizeSettings(settings);
+  if (!s.domain || !s.https) throw new Error('Enable HTTPS with a domain first: `onboarder setup`.');
+  const caddy = findOnPath('caddy');
+  if (!caddy.installed) throw new Error('Caddy is not installed. ' + installHint('caddy'));
+  const file = caddyfilePath(configFile);
+  const result = spawnSync('caddy', [action, '--config', file], { encoding: 'utf8' });
+  if (result.error) throw result.error;
+  if (result.status !== 0) {
+    const message = String(result.stderr || result.stdout || `caddy ${action} failed`).trim();
+    if (/permission denied|address already in use/i.test(message) && process.platform !== 'win32') {
+      throw new Error(`${message}\nStart the packaged service with: sudo systemctl enable --now caddy`);
+    }
+    throw new Error(message);
+  }
+  return { action, file, output: String(result.stdout || result.stderr || '').trim() };
+}

package/server/index.js

@@ -21,8 +21,9 @@ import { createRouter } from './router.js';
 import { installExitCleanup } from './sessions.js';
 import { createLogger } from './logger.js';
 import { createMcpRunner } from './mcp/runner.js';
-import { configPath, readSettings, serverUrls } from './config.js';
+import { browserUrl, configPath, isLoopbackHost, readSettings, serverUrls } from './config.js';
 import { tunnelStatus } from './tunnel.js';
+import { pidIsAlive, readPidFile, removePidFile, writePidFile } from './pidfile.js';
 
 const logger = createLogger();
 
@@ -66,11 +67,23 @@ export function startupBanner(settings, { configFile } = {}) {
   const urls = serverUrls(settings);
   const lines = ['', '  Onboarder is up.'];
   lines.push(settings.mode === 'self-hosted'
-    ? '  Mode    self-hosted — the network can reach this; every API call needs the access key'
+    ? (isLoopbackHost(settings.host)
+      ? '  Mode    self-hosted — loopback bind; use a tunnel or change the host for direct network access'
+      : '  Mode    self-hosted — the network can reach this; every API call needs the access key')
     : '  Mode    local — only this machine can reach it');
   lines.push('  Local   ' + urls.local);
   if (urls.network) lines.push('  Network ' + urls.network);
-  if (urls.domain) lines.push('  Domain  ' + urls.domain);
+  if (urls.domain) {
+    lines.push('  Domain  ' + urls.domain);
+    if (settings.domain && !settings.https) {
+      lines.push('  HTTPS   disabled — `onboarder setup` or `onboarder https setup` enables trusted TLS');
+    } else if (settings.https) {
+      lines.push('  HTTPS   Caddy obtains, renews, and terminates TLS for this domain');
+    }
+  }
+  if (settings.mode === 'self-hosted' && settings.accessKey) {
+    lines.push('  Browser this URL is opened with the access key automatically; the key is removed from the address bar.');
+  }
   if (settings.mode === 'self-hosted' && !settings.accessKey) {
     lines.push('  WARNING self-hosted with no access key — every API call is refused until one is set.');
     lines.push('          Run `onboarder setup` or `onboarder config key rotate`.');
@@ -102,6 +115,17 @@ export function openInBrowser(url) {
   }
 }
 
+export function listenError(error, { host, port, pid = null } = {}) {
+  if (error?.code === 'EADDRINUSE') {
+    const owner = pid ? ` Another Onboarder process is running as PID ${pid}.` : '';
+    return new Error(`${host}:${port} is already in use.${owner} Try \`onboarder status\`, \`onboarder stop\`, or choose another port with \`onboarder config set port <number>\`.`, { cause: error });
+  }
+  if (error?.code === 'EACCES') {
+    return new Error(`Cannot bind ${host}:${port}: permission denied. Ports below 1024 normally require elevated privileges; choose a port above 1024.`, { cause: error });
+  }
+  return error;
+}
+
 // The real boot: read the settings, bind what they say, print the banner.
 // Both `node server/index.js` and `onboarder start` land here.
 export async function startServer({ configFile = configPath(), openBrowser, log = console.log } = {}) {
@@ -116,7 +140,7 @@ export async function startServer({ configFile = configPath(), openBrowser, log
     ...CONFIG,
     configPath: configFile,
     getSettings: () => readSettings(configFile),
-    boot: { host, port },
+    boot: { host, port, domain: settings.domain, https: settings.https },
   });
 
   installExitCleanup();
@@ -130,17 +154,31 @@ export async function startServer({ configFile = configPath(), openBrowser, log
     });
   }
 
-  await new Promise((resolve, reject) => {
-    server.once('error', reject);
-    server.listen(port, host, resolve);
-  });
+  try {
+    await new Promise((resolve, reject) => {
+      server.once('error', reject);
+      server.listen(port, host, resolve);
+    });
+  } catch (error) {
+    const recorded = readPidFile(configFile);
+    throw listenError(error, { host, port, pid: recorded && pidIsAlive(recorded) ? recorded : null });
+  }
+
+  try {
+    writePidFile(configFile);
+    server.once('close', () => removePidFile(configFile));
+    process.once('exit', () => removePidFile(configFile));
+  } catch {
+    // The server is useful even when a read-only config directory cannot hold
+    // the optional process record; binding and serving are the real contract.
+  }
 
   log(startupBanner(live, { configFile }));
 
   const shouldOpen = openBrowser ?? (live.autoOpen && process.stdout.isTTY && !process.env.NO_OPEN);
-  // Remote visitors still need the key; what opens locally is the loopback URL,
-  // which in local mode needs nothing and in self-hosted mode asks for the key.
-  if (shouldOpen) openInBrowser(serverUrls(live).local);
+  // The browser adopts a self-hosted key from the query string, stores it locally,
+  // and removes the secret from the visible URL before any API request.
+  if (shouldOpen) openInBrowser(browserUrl(live));
   return { server, settings: live, host, port };
 }
 

package/server/mcp/analysis.js

@@ -206,4 +206,3 @@ export {
   docFileRow, fileFactsLine, fileStaticDoc, folderStaticDoc,
   searchDocuments,
 };
-

package/server/pidfile.js

@@ -0,0 +1,49 @@
+// Who is serving? One small file next to the config: `onboarder.pid`.
+//
+// The auto-open flow starts the server detached from the terminal that asked
+// for it, which makes "is it running?" a question ps(1) answers badly. The
+// pidfile is the answer the CLI can act on: `onboarder status` reads it,
+// `onboarder stop` kills it, and a busy-port error can say "that is us,
+// pid N" instead of shrugging. Writes are best-effort — a read-only config
+// dir must never stop the server from booting.
+
+import fs from 'node:fs';
+import path from 'node:path';
+
+export function pidPath(configFile) {
+  return path.join(path.dirname(path.resolve(configFile)), 'onboarder.pid');
+}
+
+// The pid in the file, or null when there is no file or it is garbage. A
+// garbage file is treated as absent rather than parsed charitably — it was
+// either written by us (one integer) or it is not ours to interpret.
+export function readPidFile(configFile) {
+  try {
+    const pid = Number(fs.readFileSync(pidPath(configFile), 'utf8').trim());
+    return Number.isInteger(pid) && pid > 0 ? pid : null;
+  } catch {
+    return null;
+  }
+}
+
+// Signal 0 probes existence without delivering anything. EPERM means the
+// process exists but belongs to someone else — still alive, just not ours
+// to signal.
+export function pidIsAlive(pid) {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (e) {
+    return e.code === 'EPERM';
+  }
+}
+
+export function writePidFile(configFile) {
+  fs.writeFileSync(pidPath(configFile), String(process.pid) + '\n', { mode: 0o600 });
+}
+
+// Remove the file only when it still points at `pid` — a second server that
+// rewrote the file must not lose its record because the first one exited.
+export function removePidFile(configFile, pid = process.pid) {
+  if (readPidFile(configFile) === pid) fs.rmSync(pidPath(configFile), { force: true });
+}

package/server/tunnel.js

@@ -50,6 +50,11 @@ export function tailscaleCommand(settings) {
 }
 
 export function installHint(name) {
+  if (name === 'caddy') {
+    return process.platform === 'darwin'
+      ? 'brew install caddy'
+      : 'Install Caddy with: sudo apt install caddy';
+  }
   if (name === 'cloudflared') {
     return process.platform === 'darwin'
       ? 'brew install cloudflared  (or see https://developers.cloudflare.com/cloudflare-one/connections/connect-networks/downloads/)'

package/server/.fuse_hidden0000000800000001

@@ -1,36 +0,0 @@
-// HTML to readable text, for the docs fetch. Not a parser and not trying to be:
-// the output is fed to a language model as context, so what matters is that the
-// prose survives and the markup, scripts and styles do not.
-//
-// Order is the whole trick. Script and style bodies go first — their contents are
-// text, not tags, so stripping tags first would leave a page of minified
-// JavaScript behind. The title is lifted before the general tag strip, because
-// after it there is no way to tell the title from the first paragraph. Entities
-// are decoded last, so a `<script>` written *about* HTML in the docs
-// cannot turn back into markup that the earlier passes would have removed.
-
-// Enough context for a model to summarise from without sending a whole site.
-const MAX_TEXT = 14000;
-
-const ENTITIES = {
-  '&nbsp;': ' ', '&amp;': '&', '&lt;': '<', '&gt;': '>', '&quot;': '"', '&#39;': "'",
-};
-
-export function htmlToText(html, limit = MAX_TEXT) {
-  let s = String(html);
-  s = s.replace(/<script[\s\S]*?<\/script>/gi, ' ');
-  s = s.replace(/<style[\s\S]*?<\/style>/gi, ' ');
-
-  const rawTitle = (s.match(/<title[^>]*>([\s\S]*?)<\/title>/i) || [, ''])[1];
-  const title = collapse(rawTitle.replace(/<[^>]+>/g, ' '));
-
-  s = s.replace(/<[^>]+>/g, ' ');
-  s = s.replace(/&nbsp;|&amp;|&lt;|&gt;|&quot;|&#39;/g, (m) => ENTITIES[m]);
-  // Horizontal whitespace collapses but newlines survive as paragraph breaks:
-  // a docs page read as one long line loses the structure a summary needs.
-  s = s.replace(/[ \t ]+/g, ' ').replace(/\n\s*\n+/g, '\n\n').trim();
-
-  return { title, text: s.slice(0, limit) };
-}
-
-const collapse = (s) => s.replace(/\s+/g, ' ').trim();