@sunshinelife83/hearth 1.0.0 → 1.1.0

package/README.md

@@ -81,7 +81,7 @@ hearth init
 Non-interactive (scripts, second machine):
 
 ```bash
-hearth init --yes --use both --roots ~/personal,~/work --public-url https://your-tunnel-host.example.com
+hearth init --yes --use both --roots ~/personal,~/work --public-url https://xxx.ngrok-free.dev
 ```
 
 Or one line from a checkout (checks Node, packs, installs, then runs setup
@@ -103,7 +103,8 @@ During setup, Hearth asks for:
 - which Coding Agents Hearth may use
 
 If you select ChatGPT, setup also asks which local project folders it may open
-and for your public HTTPS base URL from a tunnel or reverse proxy you control.
+and for your public HTTPS base URL — your static ngrok domain (see
+[Managed Tunnel](#managed-tunnel) below).
 A Coding Agents-only setup asks
 neither question: local commands use the current Git project, or the current
 directory outside a repository.
@@ -111,11 +112,11 @@ directory outside a repository.
 Use the public origin without `/mcp` during setup:
 
 ```text
-https://your-tunnel-host.example.com
+https://xxx.ngrok-free.dev
 ```
 
 You will configure your MCP client with the public `/mcp` URL after setup.
-Run `hearth serve` when using ChatGPT. For Coding Agents, setup prints a
+Run `hearth serve --ngrok` when using ChatGPT. For Coding Agents, setup prints a
 `skills` command and lets the Skills CLI handle installation.
 
 When the client connects, Hearth opens an Owner password approval page. Enter
@@ -140,10 +141,10 @@ The default local endpoint is:
 http://127.0.0.1:7176/mcp
 ```
 
-Most users should connect through a public HTTPS tunnel:
+Most users should connect through the managed ngrok tunnel:
 
 ```text
-https://your-tunnel-host.example.com/mcp
+https://xxx.ngrok-free.dev/mcp
 ```
 
 ChatGPT, Claude, and generic MCP clients all use the same `/mcp` endpoint.
@@ -191,24 +192,24 @@ The dashboard performs no privileged execution of its own: it shows the same
 policy-gated state the MCP surface sees, and agents/tasks are still driven
 from your MCP client.
 
-## Direct Exposure Without a Relay
+## Managed Tunnel
 
-No software can give your PC a public URL with zero outside help: ChatGPT must
-reach a public IP over valid HTTPS. What Hearth removes is the *relay
-middleman*. If you have a domain and an inbound route to this machine:
+Hearth exposes this PC through ngrok — the only remote-access path. Each PC
+gets its stable ngrok domain, and `hearth serve --ngrok` is server, URL, and
+tunnel in one command:
 
 ```bash
-hearth expose    # reports this PC's identity and exactly what's missing
-hearth id        # stable per-PC identity (hearth-xxxx...)
+ngrok config add-authtoken <your-token>   # once; token from dashboard.ngrok.com
+hearth ngrok setup --domain xxx.ngrok-free.dev
+hearth serve --ngrok
+hearth ngrok status    # health: binary, auth, live domain match
+hearth id              # stable per-PC identity (hearth-xxxx...)
 ```
 
-Then: point your domain at the machine, forward TCP 443 (and 80 for issuance),
-issue a certificate with certbot webroot against `tls.acmeDir`, set
-`tls.certFile`/`tls.keyFile`, run `hearth config set publicBaseUrl
-https://your-domain`, and restart serve. Hearth terminates TLS itself and
-serves the ACME challenge path. Without an inbound route + domain, traffic
-needs *some* relay — run your own (e.g. on your VPS), never one you don't
-control.
+Only AI endpoints (`/mcp`, OAuth, discovery, health) are reachable through
+the tunnel: the landing page and dashboard 404 remotely by Host and stay
+localhost-only. `hearth doctor` checks the binary, auth, domain match, and
+child liveness.
 
 ## Mental Model
 
@@ -220,11 +221,10 @@ connected client like a trusted coding partner with access to your machine.
 
 For a normal ChatGPT coding session:
 
-1. Start your tunnel.
-2. Run `hearth serve`.
-3. Connect the MCP client to your public `/mcp` URL.
-4. Approve the connection with the Owner password.
-5. Ask ChatGPT to open a project inside one of your allowed roots.
+1. Run `hearth serve --ngrok`.
+2. Connect the MCP client to your public `/mcp` URL.
+3. Approve the connection with the Owner password.
+4. Ask ChatGPT to open a project inside one of your allowed roots.
 
 ## Platform Support
 

package/dist/cli.js

@@ -19,6 +19,7 @@ import { generateOwnerToken, loadHearthFiles, setHearthConfigValue, setHearthCon
 import { expandHomePath } from "./roots.js";
 import { readReviewRef } from "./review-checkpoints.js";
 import { shutdownHttpServer } from "./server-shutdown.js";
+import { NGROK_AGENT_API, checkNgrokAuth, findNgrok, isNgrokChildAlive, ngrokInstallHint, ngrokPaths, ngrokVersion, normalizeNgrokDomain, parseAgentTunnels, startNgrokChild, validateManagedNgrok, validateNgrokDomain, waitForAgentDomain, } from "./tunnel-ngrok.js";
 const require = createRequire(import.meta.url);
 // Keep in sync with "engines.node" in package.json and the documented range.
 const SUPPORTED_NODE_RANGE = ">=22.19 <27";
@@ -29,7 +30,7 @@ async function main(argv) {
     switch (command) {
         case "serve":
             await ensureConfigured();
-            await serve();
+            await serve(args);
             return;
         case "mcp":
             await runMcp();
@@ -49,15 +50,15 @@ async function main(argv) {
         case "agents":
             await runAgentsCommand(args);
             return;
-        case "expose":
-            await runExpose();
-            return;
         case "id":
             runMachineId();
             return;
         case "connect":
             await runConnect(args);
             return;
+        case "ngrok":
+            await runNgrokCli(args);
+            return;
         case "show-changes":
             await runShowChanges(args);
             return;
@@ -79,8 +80,8 @@ function normalizeCommand(command) {
         || command === "config"
         || command === "agents"
         || command === "show-changes"
-        || command === "expose"
         || command === "connect"
+        || command === "ngrok"
         || command === "id")
         return command;
     if (command === "help" || command === "--help" || command === "-h")
@@ -264,22 +265,22 @@ async function runInit({ force, yes, roots, publicUrl, use, providers }) {
             }
             else if (nonInteractive) {
                 if (!files.config.server.publicBaseUrl) {
-                    throw new Error("hearth init --yes for ChatGPT requires --public-url https://your-tunnel-host.example.com (origin only, without /mcp).");
+                    throw new Error("hearth init --yes for ChatGPT requires --public-url https://xxx.ngrok-free.dev (origin only, without /mcp).");
                 }
                 publicBaseUrl = normalizePublicBaseUrl(files.config.server.publicBaseUrl);
             }
             else {
                 prompts.note([
-                    `Point your HTTPS tunnel or reverse proxy to http://127.0.0.1:${port}.`,
-                    "Paste its public URL below.",
+                    `Point ngrok at http://127.0.0.1:${port} (see \`hearth ngrok setup\`),`,
+                    "then paste its public URL below.",
                     "",
-                    "Example: https://your-tunnel-host.example.com",
+                    "Example: https://your-domain.ngrok-free.dev",
                 ].join("\n"), "Connect ChatGPT");
                 publicBaseUrl = normalizePublicBaseUrl(await textPrompt({
                     message: files.config.server.publicBaseUrl
                         ? `What public URL will ChatGPT connect to? Press Enter to keep ${files.config.server.publicBaseUrl}`
                         : "What public URL will ChatGPT connect to?",
-                    placeholder: files.config.server.publicBaseUrl ?? "https://your-tunnel-host.example.com",
+                    placeholder: files.config.server.publicBaseUrl ?? "https://xxx.ngrok-free.dev",
                     defaultValue: files.config.server.publicBaseUrl ?? "",
                     validate: validateRequiredPublicBaseUrl,
                 }));
@@ -442,7 +443,7 @@ async function runMcp() {
     const { runStdioServer } = await import("./stdio-server.js");
     await runStdioServer(loadConfig());
 }
-function logServeBanner(config, localAgentProviders, scheme) {
+function logServeBanner(config, localAgentProviders, liveDomain) {
     let machineId = "unknown";
     try {
         const { loadMachineIdentity } = require("./machine-id.js");
@@ -452,24 +453,28 @@ function logServeBanner(config, localAgentProviders, scheme) {
         // Banner must never fail because identity storage is unavailable.
     }
     const publicMcpUrl = new URL("/mcp", config.publicBaseUrl).toString();
-    console.log(`hearth listening on ${scheme}://${config.host}:${config.port}/mcp`);
+    console.log(`hearth listening on http://${config.host}:${config.port}/mcp`);
     console.log(`public MCP URL: ${publicMcpUrl}`);
+    if (liveDomain) {
+        console.log(`tunnel: ngrok ${liveDomain} live (managed — server, URL, and tunnel in one command)`);
+    }
+    else if (config.tunnel.provider === "ngrok" && config.tunnel.domain) {
+        console.log(`tunnel: ngrok ${config.tunnel.domain} saved (pass --ngrok to serve through it)`);
+    }
     console.log(`machine: ${machineId} (hearth id, diagnostic label only — not a security boundary)`);
-    console.log(`dashboard: ${scheme}://${config.host}:${config.port}/dashboard`);
+    console.log(`dashboard: http://${config.host}:${config.port}/dashboard`);
     console.log(`public base url: ${config.publicBaseUrl}`);
     console.log(`allowed roots: ${config.allowedRoots.join(", ")}`);
     console.log(`allowed hosts: ${config.allowedHosts.join(", ")}`);
     if (config.allowedHosts.includes("*")) {
         console.warn("warning: Host header allowlist is disabled because server.allowedHosts contains '*'");
     }
-    if (scheme === "https")
-        console.log("tls: native termination from tls.certFile/tls.keyFile");
     console.log("auth: Owner password approval required");
     console.log(`logging: ${config.logging.level} ${config.logging.format}`);
     console.log(`subagent providers: ${formatLocalAgentProviderStatusSummary(localAgentProviders)}`);
     console.log("next: run `hearth connect` for ChatGPT / Claude / generic MCP steps");
 }
-async function serve() {
+async function serve(argv = []) {
     const sqliteStatus = checkSqliteNative();
     if (sqliteStatus !== "ok") {
         throw new Error([
@@ -482,33 +487,31 @@ async function serve() {
     }
     const { createServer } = await import("./server.js");
     const config = loadConfig();
-    const { app, close, localAgentProviders } = createServer(config);
-    const tlsOn = Boolean(config.tls.certFile && config.tls.keyFile);
-    if (Boolean(config.tls.certFile) !== Boolean(config.tls.keyFile)) {
-        throw new Error("tls.certFile and tls.keyFile must be set together (or both left null).");
-    }
-    let httpServer;
-    if (tlsOn) {
-        const { readFileSync } = await import("node:fs");
-        const { createServer: createHttpsServer } = await import("node:https");
-        const { expandHomePath } = await import("./roots.js");
-        httpServer = createHttpsServer({
-            key: readFileSync(expandHomePath(config.tls.keyFile)),
-            cert: readFileSync(expandHomePath(config.tls.certFile)),
-        }, app).listen(config.port, config.host, () => {
-            logServeBanner(config, localAgentProviders, "https");
-        });
+    const useNgrok = argv.includes("--ngrok");
+    if (useNgrok && config.tunnel.provider !== "ngrok") {
+        throw new Error("`serve --ngrok` needs a saved ngrok domain. Run `hearth ngrok setup` first.");
     }
-    else {
-        httpServer = app.listen(config.port, config.host, () => {
-            logServeBanner(config, localAgentProviders, "http");
-        });
+    if (!useNgrok && config.tunnel.provider === "ngrok" && config.tunnel.domain) {
+        console.log(`tunnel: ngrok domain ${config.tunnel.domain} saved but --ngrok not passed; serving locally only.`);
     }
+    const managedNgrok = useNgrok ? await startManagedNgrok(config) : undefined;
+    const { app, close, localAgentProviders } = createServer(config);
+    const httpServer = app.listen(config.port, config.host, () => {
+        logServeBanner(config, localAgentProviders, managedNgrok?.domain ?? null);
+    });
     let shuttingDown = false;
     const shutdown = async () => {
         if (shuttingDown)
             return;
         shuttingDown = true;
+        if (managedNgrok) {
+            try {
+                await managedNgrok.stop();
+            }
+            catch (error) {
+                console.error(`ngrok shutdown failed: ${error instanceof Error ? error.message : String(error)}`);
+            }
+        }
         await shutdownHttpServer(httpServer, close);
         process.exit(0);
     };
@@ -561,7 +564,9 @@ async function runDoctor({ fix }) {
         console.log(`Subagents: ${config.subagents.enabled ? "enabled" : "disabled"}`);
         console.log(`Subagent providers: ${formatLocalAgentProviderStatusSummary(providers)}`);
         console.log(`Tool mode: ${config.toolMode}`);
+        console.log(`Tunnel: ${describeNgrokConfig(config.tunnel)}`);
         const warnings = [];
+        warnings.push(...checkNgrokConfig({ ...config, trustProxy: config.oauth.trustProxy }));
         if (config.allowedHosts.includes("*"))
             warnings.push("server.allowedHosts contains '*': Host header checks are disabled (local debugging only).");
         if (config.allowedRoots.length === 0)
@@ -604,13 +609,16 @@ async function runConnect(args) {
     const lines = [
         `machine: ${identity.id} (${identity.hostname})`,
         `public MCP URL (use this in remote clients): ${publicMcpUrl}`,
+        config.tunnel.provider === "ngrok" && config.tunnel.domain
+            ? `tunnel: managed ngrok (${config.tunnel.domain}) — \`hearth serve --ngrok\` starts everything`
+            : "tunnel: none managed (`hearth ngrok setup` provisions this PC's static domain)",
         `local MCP URL: ${localMcpUrl}`,
         `dashboard: http://${config.host}:${config.port}/dashboard`,
         `tool mode: ${config.toolMode} (ChatGPT works with either; Claude Desktop prefers tools.mode claude)`,
         "",
     ];
     if (wanted === "all" || wanted === "chatgpt") {
-        lines.push("ChatGPT:", `  1. hearth serve (keep running) + tunnel pointing at http://${config.host}:${config.port} (proxy the whole origin, not only /mcp).`, `  2. Add connector URL: ${publicMcpUrl}`, "  3. Approve with the Owner password from ~/.hearth/auth.json (hearth init prints it).", "");
+        lines.push("ChatGPT:", `  1. hearth serve --ngrok (keep running; it serves this PC's static domain).`, `  2. Add connector URL: ${publicMcpUrl}`, "  3. Approve with the Owner password from ~/.hearth/auth.json (hearth init prints it).", "");
     }
     if (wanted === "all" || wanted === "claude") {
         lines.push("Claude (Desktop / Code with remote MCP):", `  1. Ensure oauth.allowedRedirectHosts includes claude.ai (current: ${config.oauth.allowedRedirectHosts.join(", ")}).`, `  2. Add MCP server URL: ${publicMcpUrl} and approve with the Owner password.`, "  3. For local-only use without OAuth: hearth token create claude-local, then `hearth mcp` as a stdio server with that bearer.", "");
@@ -622,6 +630,259 @@ async function runConnect(args) {
     lines.push("The machine id is a diagnostic label, not a security boundary: copying stateDir copies the identity, so it cannot prove which PC answered or prevent cloning.");
     console.log(lines.join("\n"));
 }
+function printNgrokHelp() {
+    console.log([
+        "Hearth ngrok (managed per-PC tunnel — the only remote-access path)",
+        "",
+        "Usage:",
+        "  hearth ngrok setup [--domain <static-domain>] [--yes]",
+        "  hearth ngrok status [--json]",
+        "  hearth serve --ngrok   Start the server with the tunnel (plain serve stays local-only)",
+        "",
+        "setup saves this PC's static ngrok domain (e.g. xxx.ngrok-free.dev),",
+        "syncs server.publicBaseUrl, and enables server.trustProxy. Your ngrok",
+        "authtoken stays in ngrok's own config: run `ngrok config add-authtoken`",
+        "once if setup reports missing auth.",
+    ].join("\n"));
+}
+async function runNgrokCli(args) {
+    const [subcommand, ...rest] = args;
+    if (!subcommand || subcommand === "help" || subcommand === "--help" || subcommand === "-h") {
+        printNgrokHelp();
+        return;
+    }
+    if (subcommand === "status") {
+        await runNgrokStatus(rest.includes("--json"));
+        return;
+    }
+    if (subcommand === "setup") {
+        await runNgrokSetup(rest);
+        return;
+    }
+    throw new Error(`Unknown ngrok command: ${subcommand}. Usage: hearth ngrok <setup|status>`);
+}
+function describeNgrokConfig(tunnel) {
+    if (tunnel.provider !== "ngrok")
+        return "none (local-only until `hearth ngrok setup`)";
+    if (!tunnel.domain)
+        return "ngrok (incomplete — re-run `hearth ngrok setup`)";
+    return `ngrok ${tunnel.domain}`;
+}
+function checkNgrokConfig(config) {
+    const warnings = [];
+    if (config.tunnel.provider !== "ngrok")
+        return warnings;
+    const binary = findNgrok();
+    if (!binary) {
+        warnings.push("tunnel.provider is ngrok but no ngrok binary is on PATH.");
+        return warnings;
+    }
+    if (!config.tunnel.domain) {
+        warnings.push("Managed ngrok tunnel is incomplete (domain missing). Re-run `hearth ngrok setup`.");
+        return warnings;
+    }
+    let publicHost = "";
+    try {
+        publicHost = new URL(config.publicBaseUrl).hostname.toLowerCase();
+    }
+    catch {
+        // loadConfig already guarantees a parseable publicBaseUrl.
+    }
+    if (publicHost !== config.tunnel.domain.toLowerCase()) {
+        warnings.push(`tunnel.domain ${config.tunnel.domain} does not match publicBaseUrl host ${publicHost}. Re-run \`hearth ngrok setup\`.`);
+    }
+    if (!config.trustProxy) {
+        warnings.push("Managed ngrok needs server.trustProxy=true so rate limits see real client IPs. Re-run `hearth ngrok setup`.");
+    }
+    const childPid = isNgrokChildAlive(ngrokPaths(config.stateDir).pidPath);
+    if (childPid) {
+        warnings.push(`A serve-managed ngrok child (pid ${childPid}) looks alive while serve may not be running; restart serve --ngrok to reconcile.`);
+    }
+    return warnings;
+}
+async function runNgrokStatus(json) {
+    const files = loadHearthFiles();
+    if (!files.configExists || (!files.authExists && !process.env.HEARTH_OAUTH_OWNER_TOKEN)) {
+        throw new Error("Hearth is not configured. Run `hearth init` first, then `hearth ngrok setup`.");
+    }
+    const config = loadConfig();
+    const tunnel = config.tunnel;
+    if (tunnel.provider !== "ngrok" || !tunnel.domain) {
+        if (json) {
+            console.log(JSON.stringify({ provider: tunnel.provider, configured: false }));
+            return;
+        }
+        console.log("No managed ngrok tunnel. Run `hearth ngrok setup --domain <static-domain>` on this PC.");
+        return;
+    }
+    const binary = findNgrok();
+    let version = "unknown";
+    if (binary) {
+        try {
+            version = ngrokVersion(binary);
+        }
+        catch {
+            // Version is advisory; the auth and agent checks below are authoritative.
+        }
+    }
+    const auth = binary ? checkNgrokAuth(binary) : { ok: false, output: "ngrok not on PATH" };
+    const childPid = isNgrokChildAlive(ngrokPaths(config.stateDir).pidPath);
+    let agentUrl;
+    let agentError;
+    try {
+        const response = await fetch(`${NGROK_AGENT_API}/tunnels`);
+        if (!response.ok)
+            throw new Error(`agent API returned ${response.status}`);
+        const live = parseAgentTunnels(await response.json());
+        agentUrl = live.map((tunnel) => tunnel.publicUrl).join(", ") || undefined;
+    }
+    catch (error) {
+        agentError = error instanceof Error ? error.message : String(error);
+    }
+    if (json) {
+        console.log(JSON.stringify({
+            provider: "ngrok",
+            configured: true,
+            domain: tunnel.domain,
+            publicMcpUrl: new URL("/mcp", config.publicBaseUrl).toString(),
+            ngrok: binary ? { binary, version, authOk: auth.ok } : null,
+            childPid: childPid ?? null,
+            agentUrl: agentUrl ?? null,
+            agentError: agentError ?? null,
+        }));
+        return;
+    }
+    console.log([
+        `tunnel: ngrok ${tunnel.domain}`,
+        `public MCP URL: ${new URL("/mcp", config.publicBaseUrl).toString()}`,
+        `ngrok: ${binary ? `${binary} (${version}), auth ${auth.ok ? "ok" : "MISSING — run `ngrok config add-authtoken`"}` : "NOT FOUND on PATH"}`,
+        childPid ? `serve-managed child: running (pid ${childPid})` : "serve-managed child: not running (start with `hearth serve --ngrok`)",
+        agentUrl ? `agent serving: ${agentUrl}` : `agent: not reachable (${agentError ?? "is ngrok running?"})`,
+    ].join("\n"));
+}
+function parseNgrokSetupArgs(args) {
+    const options = { yes: false };
+    for (let index = 0; index < args.length; index += 1) {
+        const arg = args[index];
+        if (arg === "--yes" || arg === "-y")
+            options.yes = true;
+        else if (arg === "--domain")
+            options.domain = args[++index];
+        else if (arg.startsWith("--domain="))
+            options.domain = arg.slice("--domain=".length);
+        else
+            throw new Error(`Unknown ngrok setup option: ${arg}. Usage: hearth ngrok setup [--domain <static-domain>] [--yes]`);
+    }
+    return options;
+}
+async function runNgrokSetup(args) {
+    const options = parseNgrokSetupArgs(args);
+    const files = loadHearthFiles();
+    if (!files.configExists || (!files.authExists && !process.env.HEARTH_OAUTH_OWNER_TOKEN)) {
+        throw new Error("Hearth is not configured. Run `hearth init` first, then `hearth ngrok setup`.");
+    }
+    const config = loadConfig();
+    const binary = findNgrok();
+    if (!binary)
+        throw new Error(ngrokInstallHint());
+    try {
+        ngrokVersion(binary);
+    }
+    catch {
+        // Version is advisory; the auth check below is authoritative.
+    }
+    const auth = checkNgrokAuth(binary);
+    if (!auth.ok) {
+        throw new Error([
+            "ngrok has no authtoken configured.",
+            "Run `ngrok config add-authtoken <your-token>` once (token from https://dashboard.ngrok.com/get-started/your-authtoken), then re-run `hearth ngrok setup`.",
+        ].join("\n"));
+    }
+    let domain = options.domain?.trim();
+    if (domain === undefined) {
+        if (options.yes || !input.isTTY || !output.isTTY) {
+            domain = config.tunnel.domain ?? undefined;
+            if (!domain)
+                throw new Error("Non-interactive setup needs --domain <static-domain>.");
+        }
+        else {
+            prompts.note("Hearth binds this PC to its static ngrok domain (free accounts get one stable xxx.ngrok-free.dev). Only AI endpoints are reachable through it; the dashboard stays localhost-only.", "Managed ngrok");
+            domain = await textPrompt({
+                message: config.tunnel.domain
+                    ? `Which static ngrok domain should this PC serve? Press Enter to keep ${config.tunnel.domain}`
+                    : "Which static ngrok domain should this PC serve?",
+                placeholder: "xxx.ngrok-free.dev",
+                defaultValue: config.tunnel.domain ?? "",
+                validate: validateNgrokDomain,
+            });
+        }
+    }
+    const domainError = validateNgrokDomain(domain);
+    if (domainError)
+        throw new Error(domainError);
+    const normalizedDomain = normalizeNgrokDomain(domain);
+    setHearthConfigValues([
+        { path: ["tunnel", "provider"], value: "ngrok" },
+        { path: ["tunnel", "domain"], value: normalizedDomain },
+        { path: ["server", "publicBaseUrl"], value: `https://${normalizedDomain}` },
+        { path: ["server", "trustProxy"], value: true },
+    ]);
+    const lines = [
+        `Domain: ${normalizedDomain}`,
+        `Public MCP URL: https://${normalizedDomain}/mcp`,
+        "server.trustProxy was enabled so rate limits see real client IPs via x-forwarded-for.",
+        "Note: ngrok free shows a browser interstitial page on HTML traffic; API calls are unaffected. The Owner approval page needs one click-through.",
+    ];
+    if (options.yes || !input.isTTY || !output.isTTY) {
+        console.log(["Hearth ngrok is ready", ...lines].join("\n"));
+    }
+    else {
+        prompts.note(lines.join("\n"), "Hearth ngrok is ready");
+        prompts.outro("Run `hearth serve --ngrok` — server and tunnel start together. `hearth ngrok status` checks health.");
+    }
+}
+/**
+ * Validate managed-ngrok config and start the supervised agent.
+ * Fail-fast: an ngrok setup that cannot serve the saved domain must stop
+ * `serve`, never leave Hearth reachable locally but dark publicly.
+ */
+async function startManagedNgrok(config) {
+    const binary = findNgrok();
+    const problems = validateManagedNgrok({
+        domain: config.tunnel.domain,
+        publicBaseUrl: config.publicBaseUrl,
+        trustProxy: config.oauth.trustProxy,
+        binary,
+    });
+    if (problems.length > 0) {
+        throw new Error(["Managed ngrok is misconfigured:", ...problems.map((problem) => `  - ${problem}`)].join("\n"));
+    }
+    if (binary && !checkNgrokAuth(binary).ok) {
+        throw new Error("ngrok has no authtoken configured. Run `ngrok config add-authtoken <your-token>`, then restart serve.");
+    }
+    const paths = ngrokPaths(config.stateDir);
+    console.log(`tunnel: starting managed ngrok for ${config.tunnel.domain} ...`);
+    const supervised = startNgrokChild({
+        binary: binary,
+        port: config.port,
+        pidPath: paths.pidPath,
+        onLog: (line) => console.error(`[ngrok] ${line}`),
+    });
+    supervised.process.once("exit", (code) => {
+        if (code !== 0 && code !== null) {
+            console.error(`[ngrok] agent exited with code ${code}; public URL is dark while serve keeps running locally. Restart serve --ngrok or run \`hearth ngrok status\`.`);
+        }
+    });
+    try {
+        await waitForAgentDomain(config.tunnel.domain);
+    }
+    catch (error) {
+        await supervised.stop().catch(() => undefined);
+        throw error instanceof Error ? error : new Error(String(error));
+    }
+    console.log(`tunnel: ngrok serving https://${config.tunnel.domain} (static domain confirmed live)`);
+    return { stop: supervised.stop, domain: config.tunnel.domain };
+}
 function runConfigCommand(args) {
     const [subcommand, key, ...rest] = args;
     const files = loadHearthFiles();
@@ -649,76 +910,17 @@ function runMachineId() {
         console.log(JSON.stringify(identity, null, 2));
     });
 }
-/**
- * Relay-free exposure report: tells the owner exactly what stands between
- * this PC and a direct public URL, without routing through any tunnel
- * service. Honest by design: a public URL needs (1) an inbound route to this
- * machine and (2) a domain with a valid certificate. Hearth automates
- * everything after those two owner-provided prerequisites.
- */
-async function runExpose() {
-    const config = loadConfig();
-    const { loadMachineIdentity } = await import("./machine-id.js");
-    const identity = loadMachineIdentity(config.stateDir);
-    const { execFileSync } = await import("node:child_process");
-    const { existsSync } = await import("node:fs");
-    const { expandHomePath } = await import("./roots.js");
-    let publicIp;
-    try {
-        const out = execFileSync("dig", ["+short", "+time=5", "myip.opendns.com", "@resolver1.opendns.com"], {
-            encoding: "utf8",
-            timeout: 10_000,
-        }).trim().split("\n").pop()?.trim();
-        if (out && /^[0-9a-fA-F.:]+$/.test(out))
-            publicIp = out;
-    }
-    catch {
-        // dig absent or blocked: report without a public IP guess.
-    }
-    const certSet = Boolean(config.tls.certFile && config.tls.keyFile);
-    const certPresent = certSet
-        && existsSync(expandHomePath(config.tls.certFile))
-        && existsSync(expandHomePath(config.tls.keyFile));
-    const publicUrl = new URL(config.publicBaseUrl);
-    const directHttps = publicUrl.protocol === "https:" && certSet;
-    const lines = [
-        `machine: ${identity.id} (${identity.hostname}, ${identity.platform}/${identity.arch})`,
-        `bind: ${config.host}:${config.port}  (hearth serve)`,
-        `public base url: ${config.publicBaseUrl}`,
-        `public MCP URL (keep one URL per PC — reusing it elsewhere splits approvals and audit): ${new URL("/mcp", config.publicBaseUrl).toString()}`,
-        `public IP seen from here: ${publicIp ?? "unknown (dig unavailable or blocked)"}`,
-        `native TLS: ${!certSet ? "off (tls.certFile/tls.keyFile unset)" : certPresent ? "cert + key present" : "CONFIGURED BUT FILES MISSING"}`,
-        `ACME webroot: ${config.tls.acmeDir ?? "unset"}`,
-        "",
-        "OAuth tokens are bound to this machine's resource URL and Owner password.",
-        "Run `hearth connect` for ChatGPT / Claude / generic MCP steps.",
-        "",
-        directHttps && certPresent
-            ? "status: DIRECT — publicBaseUrl is https and TLS material is present. Forward TCP 443 to this machine, point your domain's A/AAAA record at the public IP, restart serve."
-            : "status: NOT directly reachable — to drop the relay you need:",
-        ...(!directHttps || !certPresent ? [
-            "  1. A domain whose A/AAAA record points at this machine (public IP above).",
-            "  2. TCP 443 (and TCP 80 for issuance) forwarded to this machine.",
-            "  3. Certificates, e.g.: certbot certonly --webroot -w <dir> -d <domain>",
-            "     with tls.acmeDir set to <dir> so Hearth serves the HTTP-01 challenge.",
-            "  4. tls.certFile/tls.keyFile set to the issued files,",
-            "     hearth config set publicBaseUrl https://<domain>, then restart serve.",
-        ] : []),
-        "",
-        "Without an inbound route + domain, some relay must carry the traffic;",
-        "that relay can be your own VPS — never a third party you don't control.",
-    ];
-    console.log(lines.join("\n"));
-}
 function printHelp() {
     console.log([
         "Hearth",
         "",
         "Usage:",
         "  hearth                 Run first-time setup if needed, then start the server",
-        "  hearth serve           Start the server",
+        "  hearth serve [--ngrok]   Start the server (add --ngrok to also start the managed tunnel)",
         "  hearth init [--force] [--yes --use chatgpt|coding-agents|both --roots <csv> --public-url <url> --providers <csv>]",
         "  hearth doctor [--fix]  Show config, runtime, and native dependency status",
+        "  hearth ngrok setup [--domain <static-domain>] [--yes]",
+        "  hearth ngrok status [--json]  Managed per-PC ngrok tunnel",
         "  hearth connect [chatgpt|claude|generic]  Print copy-paste MCP connection steps for this PC",
         "  hearth config get      Print persisted config",
         "  hearth config set publicBaseUrl <url|null>  (origin only, without /mcp)",
@@ -728,7 +930,6 @@ function printHelp() {
         "  hearth agents continue <id> [--model <model>] [--effort <level>] <prompt>",
         "  hearth agents show <id>",
         "  hearth agents daemon <status|stop|logs>",
-        "  hearth expose          Relay-free exposure report for this PC (own domain + TLS)",
         "  hearth id              Print this machine's stable Hearth identity",
         "  hearth -v, --version   Print the installed version",
         "",
@@ -739,7 +940,7 @@ function printHelp() {
         "  hearth connect",
         "",
         "For temporary tunnels:",
-        "  hearth config set publicBaseUrl https://your-tunnel-host.example.com",
+        "  hearth config set publicBaseUrl https://xxx.ngrok-free.dev",
         "  hearth serve",
     ].join("\n"));
 }
@@ -1029,7 +1230,7 @@ function validatePublicBaseUrl(value) {
             : "Use an http or https URL.";
     }
     catch {
-        return "Enter a valid URL, for example https://your-tunnel-host.example.com.";
+        return "Enter a valid URL, for example https://xxx.ngrok-free.dev.";
     }
 }
 function assertSupportedNode() {