@sunshinelife83/hearth 1.0.0 → 1.1.0

package/dist/config-schema.js

@@ -15,15 +15,16 @@ const serverConfigSchema = z.object({
     // OAuth clients; only meaningful for local/LAN-only deployments.
     issuerMode: z.enum(["derived", "local"]).default("derived"),
 }).strict().prefault({});
-const tlsConfigSchema = z.object({
-    // Native TLS for relay-free direct exposure: when both are set, `serve`
-    // terminates HTTPS itself (e.g. behind your own domain + port forward).
-    // Leave null when running behind localhost or a tunnel that terminates TLS.
-    certFile: z.string().trim().min(1).nullable().default(null),
-    keyFile: z.string().trim().min(1).nullable().default(null),
-    // Directory served (read-only) at /.well-known/acme-challenge/ so certbot
-    // webroot mode can provision certificates while the server runs.
-    acmeDir: z.string().trim().min(1).nullable().default(null),
+const tunnelConfigSchema = z.object({
+    // Managed per-PC tunnel. "none" serves locally only. "ngrok" lets
+    // `hearth ngrok setup` save this PC's static ngrok domain and
+    // `hearth serve --ngrok` supervise the agent, so one command is
+    // server + URL + tunnel.
+    provider: z.enum(["none", "ngrok"]).default("none"),
+    // Static ngrok domain for this PC (e.g. xxx.ngrok-free.dev).
+    // `hearth ngrok setup` sets this and keeps server.publicBaseUrl in sync.
+    // The ngrok authtoken itself lives in ngrok's own config, never here.
+    domain: z.string().trim().min(1).nullable().default(null),
 }).strict().prefault({});
 const workspaceProfileSchema = z.object({
     path: z.string().trim().min(1).describe("Absolute path (or ~-prefixed) this profile applies to; longest prefix wins."),
@@ -117,7 +118,7 @@ export const hearthConfigSchema = z.object({
     fleet: fleetConfigSchema.default({ lanes: {} }),
     execution: executionConfigSchema,
     logging: loggingConfigSchema,
-    tls: tlsConfigSchema.default({ certFile: null, keyFile: null, acmeDir: null }),
+    tunnel: tunnelConfigSchema.default({ provider: "none", domain: null }),
     oauth: oauthConfigSchema,
 }).strict();
 export function defaultHearthConfig() {

package/dist/config.js

@@ -7,12 +7,16 @@ export function loadConfig(env = process.env) {
     const host = stored.server.host;
     const port = stored.server.port;
     const publicBaseUrl = parsePublicBaseUrl(stored.server.publicBaseUrl ?? localPublicBaseUrl(host, port));
+    const tunnelDomain = stored.tunnel.provider === "ngrok" && stored.tunnel.domain
+        ? parseTunnelDomain(stored.tunnel.domain)
+        : null;
     const derivedAllowedHosts = [
         "localhost",
         "127.0.0.1",
         "::1",
         host,
         new URL(publicBaseUrl).hostname,
+        ...(tunnelDomain ? [tunnelDomain] : []),
         ...stored.server.allowedHosts,
     ];
     return {
@@ -68,10 +72,9 @@ export function loadConfig(env = process.env) {
             ...stored.logging,
             trustProxy: stored.server.trustProxy,
         },
-        tls: {
-            certFile: stored.tls.certFile,
-            keyFile: stored.tls.keyFile,
-            acmeDir: stored.tls.acmeDir,
+        tunnel: {
+            provider: stored.tunnel.provider,
+            domain: stored.tunnel.domain,
         },
     };
 }
@@ -96,6 +99,12 @@ function parseRequiredSecret(value) {
     }
     return secret;
 }
+function parseTunnelDomain(value) {
+    const trimmed = value.trim().replace(/^https?:\/\//i, "").split("/")[0].trim();
+    if (!trimmed || /\s/.test(trimmed))
+        return null;
+    return trimmed.toLowerCase();
+}
 function parsePublicBaseUrl(value) {
     const parsed = new URL(value);
     parsed.hash = "";

package/dist/dashboard/app.js

@@ -202,7 +202,7 @@ const renderers = {
           <div>Public MCP URL: <code>${esc(mcpUrl)}</code></div>
           <div class="muted">Local: <code>${esc(s.mcpEndpoint)}</code> · health: <code>${esc(s.healthEndpoint)}</code> · tool mode: <code>${esc(s.toolMode || "")}</code></div></div>
         <div class="card"><h3>ChatGPT</h3>
-          <ol><li>Keep <code>hearth serve</code> running; tunnel must proxy the whole origin, not only <code>/mcp</code>.</li>
+          <ol><li>Keep <code>hearth serve --ngrok</code> running.</li>
           <li>Add connector URL <code>${esc(mcpUrl)}</code>.</li>
           <li>Approve with the Owner password (<code>~/.hearth/auth.json</code>).</li></ol></div>
         <div class="card"><h3>Claude</h3>

package/dist/dashboard/landing.html

@@ -26,9 +26,9 @@ hearth serve</pre>
   <div class="card">
     <h3>Use it</h3>
     <ol>
-      <li>Run <code>hearth serve</code> (or <code>hearth mcp</code> for local stdio).</li>
+      <li>Run <code>hearth serve --ngrok</code> (or <code>hearth mcp</code> for local stdio).</li>
       <li>Open the <a href="/dashboard">local dashboard</a> and sign in with your Owner password.</li>
-      <li>Run <code>hearth connect</code> and paste the public <code>/mcp</code> URL into your MCP client (via your own tunnel for remote clients).</li>
+      <li>Run <code>hearth connect</code> and paste the public <code>/mcp</code> URL into your MCP client (served through this PC's ngrok domain when running <code>serve --ngrok</code>).</li>
       <li>Ask it to open a project, plan a task, delegate to a coding agent, verify, land.</li>
     </ol>
   </div>

package/dist/logger.js

@@ -61,9 +61,6 @@ export function logEvent(config, level, event, fields = {}) {
 }
 export function requestIp(req, trustProxy) {
     if (trustProxy) {
-        const cfConnectingIp = firstHeaderValue(req.header("cf-connecting-ip"));
-        if (cfConnectingIp)
-            return cfConnectingIp;
         const forwardedFor = firstHeaderValue(req.header("x-forwarded-for"));
         if (forwardedFor)
             return forwardedFor;

package/dist/server.js

@@ -16,7 +16,6 @@ import { isArtifactDownloadSupportedPlatform, registerArtifactTools, } from "./a
 import { registerAgentTools } from "./agent-tools.js";
 import { registerDashboard, dashboardDirectory } from "./dashboard.js";
 import { loadMachineIdentity } from "./machine-id.js";
-import { expandHomePath } from "./roots.js";
 import { registerTaskTools } from "./task-tools.js";
 import { registerContextTools } from "./context/context-tools.js";
 import { TaskStore } from "./task-store.js";
@@ -153,6 +152,22 @@ function requestLogFields(req, config) {
 function assetBaseUrl(config) {
     return `${config.publicBaseUrl.replace(/\/+$/, "")}/mcp-app-assets`;
 }
+/**
+ * ngrok forwards the whole origin, but only AI endpoints may be reachable
+ * remotely. Refuse the landing page and dashboard when the request arrived
+ * through the configured tunnel domain; localhost stays fully available.
+ */
+function denyTunnelHost(config) {
+    return (req, res, next) => {
+        const domain = config.tunnel.provider === "ngrok" ? config.tunnel.domain?.toLowerCase() : null;
+        if (domain && (req.hostname ?? "").toLowerCase() === domain) {
+            logEvent(config.logging, "warn", "tunnel_remote_denied", { path: requestPath(req) });
+            res.status(404).json({ error: "Not found" });
+            return;
+        }
+        next();
+    };
+}
 function uiManifestUrl() {
     return new URL("../dist/ui/.vite/manifest.json", import.meta.url);
 }
@@ -850,16 +865,10 @@ export function createServer(config = loadConfig(), options = {}) {
             mcp: new URL("/mcp", config.publicBaseUrl).toString(),
         });
     });
-    // ACME HTTP-01 challenge passthrough for relay-free TLS: serve only
-    // /.well-known/acme-challenge/* from the configured directory so certbot
-    // webroot mode works while the server runs. Nothing else is exposed here.
-    if (config.tls.acmeDir) {
-        const acmeDir = expandHomePath(config.tls.acmeDir);
-        app.use("/.well-known/acme-challenge", express.static(acmeDir, { fallthrough: false, maxAge: 0 }));
-    }
-    app.get("/", (_req, res) => {
+    app.get("/", denyTunnelHost(config), (_req, res) => {
         res.sendFile("landing.html", { root: dashboardDirectory() });
     });
+    app.use("/dashboard", denyTunnelHost(config));
     registerDashboard(app, {
         config,
         workspaces,

package/dist/tunnel-ngrok.js

@@ -0,0 +1,270 @@
+import { execFileSync, spawn } from "node:child_process";
+import { accessSync, constants, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { delimiter, join, resolve } from "node:path";
+/**
+ * Managed per-PC ngrok tunnel — the sole remote-access path.
+ *
+ * Each PC runs `ngrok http <port>` for its own free static dev domain
+ * (e.g. https://xxx.ngrok-free.dev), which never churns across restarts.
+ * Hearth supervises the agent, reads the live public URL from the local
+ * agent API (127.0.0.1:4040) instead of parsing logs, and refuses to serve
+ * publicly when the live domain drifts from the saved one.
+ *
+ * The ngrok authtoken is ngrok's own secret: it lives in ngrok's config via
+ * `ngrok config add-authtoken` and is never stored in Hearth config.
+ */
+export const NGROK_AGENT_API = "http://127.0.0.1:4040/api";
+export function ngrokPaths(stateDir) {
+    const dir = join(stateDir, "tunnels", "ngrok");
+    return { dir, pidPath: join(dir, "ngrok.pid") };
+}
+export function findNgrok(env = process.env) {
+    const pathValue = env.PATH;
+    if (!pathValue)
+        return undefined;
+    const binary = process.platform === "win32" ? "ngrok.exe" : "ngrok";
+    for (const directory of pathValue.split(delimiter)) {
+        if (!directory)
+            continue;
+        const candidate = resolve(directory, binary);
+        try {
+            accessSync(candidate, constants.X_OK);
+            return candidate;
+        }
+        catch {
+            // Not executable here; keep scanning.
+        }
+    }
+    return undefined;
+}
+export function ngrokInstallHint() {
+    return [
+        "ngrok was not found on PATH.",
+        "Install it first, then re-run `hearth ngrok setup`:",
+        "  Linux/macOS: brew install ngrok  (or https://ngrok.com/download)",
+        "  Windows: winget install --id Ngrok.ngrok",
+    ].join("\n");
+}
+function runNgrok(binary, args) {
+    try {
+        const output = execFileSync(binary, args, {
+            encoding: "utf8",
+            timeout: 30_000,
+            maxBuffer: 1024 * 1024,
+        });
+        return { ok: true, output };
+    }
+    catch (error) {
+        const stderr = error.stderr;
+        const stdout = error.stdout;
+        const message = error instanceof Error ? error.message : String(error);
+        return {
+            ok: false,
+            output: [typeof stdout === "string" ? stdout : "", typeof stderr === "string" ? stderr : "", message]
+                .filter(Boolean)
+                .join("\n"),
+        };
+    }
+}
+export function ngrokVersion(binary) {
+    const result = runNgrok(binary, ["version"]);
+    if (!result.ok)
+        throw new Error(`ngrok version check failed:\n${result.output}`);
+    return result.output.trim().split("\n")[0] ?? "unknown";
+}
+/** An authtoken is configured when `ngrok config check` succeeds. */
+export function checkNgrokAuth(binary) {
+    return runNgrok(binary, ["config", "check"]);
+}
+export function validateNgrokDomain(value) {
+    const trimmed = value?.trim() ?? "";
+    if (!trimmed)
+        return "Enter the static ngrok domain for this PC, for example xxx.ngrok-free.dev.";
+    const bare = trimmed.replace(/^https?:\/\//i, "").split("/")[0] ?? "";
+    if (!bare || /\s/.test(bare) || bare.includes(":") || bare.includes("/")) {
+        return "Enter a bare domain such as xxx.ngrok-free.dev (no scheme, path, or port).";
+    }
+    if (/\/mcp\/?$/i.test(trimmed))
+        return "Enter the domain only, without /mcp.";
+    if (!bare.includes("."))
+        return `That does not look like an ngrok domain: ${JSON.stringify(bare)}.`;
+    return undefined;
+}
+export function normalizeNgrokDomain(value) {
+    return value.trim().replace(/^https?:\/\//i, "").split("/")[0].trim().toLowerCase();
+}
+/** Parse `GET /api/tunnels` into https tunnels. Pure and unit-tested. */
+export function parseAgentTunnels(payload) {
+    if (typeof payload !== "object" || payload === null)
+        return [];
+    const tunnels = payload.tunnels;
+    if (!Array.isArray(tunnels))
+        return [];
+    const result = [];
+    for (const entry of tunnels) {
+        if (typeof entry !== "object" || entry === null)
+            continue;
+        const { public_url: publicUrl, proto } = entry;
+        if (typeof publicUrl !== "string" || typeof proto !== "string")
+            continue;
+        if (proto !== "https")
+            continue;
+        result.push({ publicUrl, proto });
+    }
+    return result;
+}
+async function fetchAgentTunnels() {
+    const response = await fetch(`${NGROK_AGENT_API}/tunnels`);
+    if (!response.ok)
+        throw new Error(`ngrok agent API returned ${response.status}`);
+    return parseAgentTunnels(await response.json());
+}
+/** Wait for an https tunnel whose host equals the saved domain. Throws on timeout or drift. */
+export async function waitForAgentDomain(domain, options = {}) {
+    const timeoutMs = options.timeoutMs ?? 45_000;
+    const pollMs = options.pollMs ?? 1_000;
+    const deadline = Date.now() + timeoutMs;
+    let lastSeen;
+    for (;;) {
+        let tunnels = [];
+        try {
+            tunnels = await fetchAgentTunnels();
+        }
+        catch {
+            // Agent not up yet; keep polling until the deadline.
+        }
+        const match = tunnels.find((tunnel) => {
+            try {
+                return new URL(tunnel.publicUrl).hostname.toLowerCase() === domain.toLowerCase();
+            }
+            catch {
+                return false;
+            }
+        });
+        if (match)
+            return match.publicUrl;
+        if (tunnels.length > 0) {
+            lastSeen = tunnels.map((tunnel) => tunnel.publicUrl).join(", ");
+        }
+        if (Date.now() >= deadline) {
+            throw new Error(lastSeen
+                ? `ngrok is serving ${lastSeen} instead of the saved domain ${domain}. Fix the domain (hearth ngrok setup) — refusing to serve a drifting URL.`
+                : `Timed out waiting for ngrok to serve ${domain}. Is the agent running with this domain and a valid authtoken?`);
+        }
+        await new Promise((resolveSleep) => setTimeout(resolveSleep, pollMs));
+    }
+}
+export function startNgrokChild(options) {
+    mkdirSync(join(options.pidPath, ".."), { recursive: true, mode: 0o700 });
+    const child = spawn(options.binary, ["http", String(options.port), "--log=stdout", "--log-format=json"], {
+        stdio: ["ignore", "pipe", "pipe"],
+        windowsHide: true,
+    });
+    if (child.pid === undefined) {
+        throw new Error("ngrok child exited before a pid was assigned.");
+    }
+    const pid = child.pid;
+    try {
+        writeFileSync(options.pidPath, `${pid}\n`, { mode: 0o600 });
+    }
+    catch {
+        // Pidfile is advisory; the child reference is authoritative.
+    }
+    const forward = (chunk) => {
+        for (const line of String(chunk).split("\n")) {
+            const trimmed = line.trim();
+            if (!trimmed)
+                continue;
+            try {
+                const logged = JSON.parse(trimmed);
+                if (typeof logged.msg === "string") {
+                    options.onLog(`${String(logged.lvl ?? "info")}: ${logged.msg}${logged.err ? ` (${String(logged.err)})` : ""}`);
+                    continue;
+                }
+            }
+            catch {
+                // Not JSON; fall through to raw output.
+            }
+            options.onLog(trimmed);
+        }
+    };
+    child.stdout?.on("data", forward);
+    child.stderr?.on("data", forward);
+    return {
+        process: child,
+        pid,
+        stop: () => new Promise((resolveStop) => {
+            let settled = false;
+            const finish = () => {
+                if (!settled) {
+                    settled = true;
+                    resolveStop();
+                }
+            };
+            child.once("exit", finish);
+            child.once("error", finish);
+            try {
+                child.kill("SIGTERM");
+            }
+            catch {
+                finish();
+            }
+            setTimeout(() => {
+                try {
+                    child.kill("SIGKILL");
+                }
+                catch {
+                    // Already gone.
+                }
+                finish();
+            }, 10_000).unref?.();
+        }),
+    };
+}
+/** Best-effort liveness check for a serve-managed ngrok child. */
+export function isNgrokChildAlive(pidPath) {
+    let pid;
+    try {
+        const parsed = Number.parseInt(readFileSync(pidPath, "utf8").trim(), 10);
+        if (Number.isInteger(parsed) && parsed > 0)
+            pid = parsed;
+    }
+    catch {
+        return undefined;
+    }
+    if (pid === undefined)
+        return undefined;
+    try {
+        process.kill(pid, 0);
+        return pid;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Serve-time fail-fast validation. Returns blocking problem strings. */
+export function validateManagedNgrok(state) {
+    const problems = [];
+    if (!state.domain) {
+        problems.push("`serve --ngrok` needs a saved domain. Run `hearth ngrok setup` first.");
+        return problems;
+    }
+    let publicHost = "";
+    try {
+        publicHost = new URL(state.publicBaseUrl).hostname.toLowerCase();
+    }
+    catch {
+        problems.push(`server.publicBaseUrl ${JSON.stringify(state.publicBaseUrl)} is not a valid URL.`);
+    }
+    if (publicHost && publicHost !== state.domain.toLowerCase()) {
+        problems.push(`tunnel.domain ${state.domain} does not match publicBaseUrl host ${publicHost}. ` +
+            "Re-run `hearth ngrok setup` to resync.");
+    }
+    if (!state.trustProxy) {
+        problems.push("Managed ngrok needs server.trustProxy=true. Re-run `hearth ngrok setup`.");
+    }
+    if (!state.binary) {
+        problems.push(ngrokInstallHint());
+    }
+    return problems;
+}

package/dist/user-config.js

@@ -185,9 +185,36 @@ function parseJsoncConfig(source, filePath) {
         return hearthConfigSchema.parse(value);
     }
     catch (error) {
-        throw fileError("read", filePath, error);
+        throw fileError("read", filePath, withLegacyTunnelHint(value, error));
     }
 }
+/**
+ * One-time breaking migration aid: pre-ngrok configs carry a `tls` section
+ * and cloudflared-era `tunnel` keys that strict validation rejects. Detect
+ * them and tell the owner exactly how to migrate instead of dumping Zod.
+ */
+function withLegacyTunnelHint(value, error) {
+    if (!(error instanceof z.ZodError))
+        return error;
+    if (typeof value !== "object" || value === null)
+        return error;
+    const record = value;
+    const tunnel = record.tunnel;
+    const stale = [];
+    if ("tls" in record)
+        stale.push("`tls`");
+    if (tunnel !== null && typeof tunnel === "object" && tunnel !== undefined
+        && (tunnel.provider === "cloudflared" || "hostname" in tunnel || "tunnelId" in tunnel)) {
+        stale.push("cloudflared-era `tunnel` keys");
+    }
+    if (stale.length === 0)
+        return error;
+    const reason = error instanceof Error ? error.message : String(error);
+    return new Error(`${reason}\nYour config predates ngrok-only Hearth (stale ${stale.join(" and ")}). ` +
+        "To migrate: delete the `tls` section from your config.jsonc, re-run " +
+        "`hearth ngrok setup --domain <your-static-domain>` to recreate `tunnel`, " +
+        "and restart serve (auth.json is untouched).");
+}
 function serializeConfig(config) {
     return `${JSON.stringify(config, null, 2)}\n`;
 }

package/docs/configuration.md

@@ -30,6 +30,13 @@ Run `hearth init` to create both files. `hearth config set publicBaseUrl
     "allowedHosts": [],
     "trustProxy": false,
   },
+  "tunnel": {
+    // Managed per-PC ngrok tunnel. `hearth ngrok setup` writes this section,
+    // keeps publicBaseUrl in sync, and enables trustProxy. The ngrok
+    // authtoken lives in ngrok's own config, never here.
+    "provider": "none",
+    "domain": null,
+  },
   "workspaces": {
     "allowedRoots": ["~/personal", "~/work"],
     "worktreeRoot": "~/.hearth/worktrees",

package/docs/gotchas.md

@@ -2,6 +2,25 @@
 
 This page collects the setup issues users are most likely to hit.
 
+## npm Install Warnings (deprecated, funding, allow-scripts)
+
+These are noise, with one exception:
+
+- `deprecated prebuild-install` / `node-domexception`: transitive dependencies
+  of `better-sqlite3` and the fetch stack. Harmless; they come from upstream
+  packages, not Hearth.
+- `looking for funding`: informational. Ignore it.
+- `allow-scripts ... not yet covered`: npm 11+ gates install scripts. Hearth
+  needs its own postinstall plus the `better-sqlite3` and `node-pty` native
+  builds. If `hearth doctor` later reports `SQLite native dependency` as
+  anything but `ok`, reinstall with the scripts pre-approved:
+
+```bash
+npm install -g --allow-scripts="@sunshinelife83/hearth,better-sqlite3,node-pty" @sunshinelife83/hearth
+```
+
+`./install.sh` already passes these flags on the npm path.
+
 ## `hearth` Command Not Found
 
 Use `npx`:
@@ -50,45 +69,66 @@ Release starts run a native dependency check before launching.
 Use the origin for setup:
 
 ```text
-https://your-tunnel-host.example.com
+https://xxx.ngrok-free.dev
 ```
 
 Use the MCP endpoint in the client:
 
 ```text
-https://your-tunnel-host.example.com/mcp
+https://xxx.ngrok-free.dev/mcp
 ```
 
 If you saved the wrong value:
 
 ```bash
-npx @sunshinelife83/hearth config set publicBaseUrl https://your-tunnel-host.example.com
+npx @sunshinelife83/hearth config set publicBaseUrl https://xxx.ngrok-free.dev
 ```
 
 ## Reverse Proxy `/mcp` Returns 404
-Proxy the whole Hearth server from the root of your tunnel or reverse proxy.
-
-Do not mount only `/mcp`: some proxies strip a configured mount path before
-proxying to the local service, so a public `/mcp` request can otherwise arrive
-at Hearth as `/`. Hearth also needs OAuth routes outside `/mcp`, so serving
-the whole local origin is the correct setup.
+ngrok forwards the whole origin, so this only bites manual setups: never
+mount only `/mcp` in front of Hearth. Hearth needs its OAuth routes outside
+`/mcp`, and a path-scoped mount can strip `/mcp` before the request arrives
+(arriving as `/` and failing).
 
 ## Tunnel URL Changed
 
-Temporary tunnels often change URLs between runs.
-
-Update the configured URL:
+It should not: the managed ngrok domain is static. If the served domain and
+the saved one disagree, something replaced your agent or domain:
 
 ```bash
-npx @sunshinelife83/hearth config set publicBaseUrl https://new-tunnel.example.com
+npx @sunshinelife83/hearth ngrok status
+npx @sunshinelife83/hearth doctor
 ```
 
-For a stable URL:
+If you intentionally moved to a new domain, resync and restart:
 
 ```bash
-npx @sunshinelife83/hearth config set publicBaseUrl https://hearth.example.com
+npx @sunshinelife83/hearth ngrok setup --domain https://new-domain.ngrok-free.dev
+npx @sunshinelife83/hearth serve --ngrok
 ```
 
+## Managed ngrok Problems
+
+Run `hearth ngrok status` and `hearth doctor` first; most answers are there.
+
+- **`ngrok was not found`**: install the binary (see `hearth ngrok setup`
+  output), then re-run setup.
+- **No authtoken**: run `ngrok config add-authtoken <your-token>` once, then
+  re-run setup.
+- **Agent serving a different domain than saved**: another agent (or account)
+  is running. `serve --ngrok` refuses to start in this state — stop the other
+  agent, then restart. Never silence this check: serving under a drifting URL
+  invalidates OAuth sessions.
+- **Hostname unreachable**: the ngrok agent is down. Restart
+  `hearth serve --ngrok` and check `hearth ngrok status`.
+- **Hostname resolves but Hearth rejects with 403**: the tunnel domain and
+  `server.publicBaseUrl` disagree. Re-run setup for the right domain.
+- **Owner approval page shows an ngrok warning first**: expected on the free
+  tier — click through the interstitial once, then approve normally. API
+  calls are unaffected.
+- **`/dashboard` unreachable remotely**: intentional. Remote dashboard and
+  landing requests 404 by Host; the dashboard stays localhost-only.
+
 ## Host Header Or 403 Problems
 
 Hearth derives allowed hosts from the configured public URL.
@@ -99,8 +139,8 @@ Run:
 npx @sunshinelife83/hearth doctor
 ```
 
-Confirm the public URL hostname appears in allowed hosts. If you changed tunnel
-URLs, update `publicBaseUrl`.
+Confirm the public URL hostname appears in allowed hosts. If you replaced the
+managed domain, resync with `hearth ngrok setup`.
 
 For intentional local debugging only, set `server.allowedHosts` to `["*"]` in
 `~/.hearth/config.jsonc`.

package/docs/security.md

@@ -57,7 +57,7 @@ discover OAuth metadata and connect to the correct resource.
 The value should be the origin only:
 
 ```text
-https://your-tunnel-host.example.com
+https://xxx.ngrok-free.dev
 ```
 
 Do not include `/mcp` in `server.publicBaseUrl`.
@@ -82,16 +82,38 @@ Future direction: a per-device keypair whose private key never leaves the PC
 `hearth id`, `/healthz`, the dashboard, and approvals, so audit entries can
 bind to an unclonable key.
 
+## Managed Tunnel (ngrok)
+
+`hearth ngrok setup` binds this PC to its static ngrok domain. Trust
+implications:
+
+- **Only AI endpoints are reachable remotely.** Hearth refuses the landing
+  page and dashboard for tunnel-domain Hosts (404); `/mcp`, OAuth,
+  discovery, and health serve normally. The dashboard remains a
+  localhost-only surface behind the Owner password.
+- **The authtoken is ngrok's secret, not Hearth's.** It lives in ngrok's own
+  config (`ngrok config add-authtoken`); Hearth only saves the public domain.
+  Anyone holding your authtoken can tunnel as you: guard it, and rotate it
+  from the ngrok dashboard if exposed.
+- **Rate limiting sees real IPs.** Setup enables `server.trustProxy` so
+  `x-forwarded-for` feeds rate-limit keys; without it every client would
+  share the tunnel's localhost key.
+- **ngrok sees TLS plaintext** between its edge and your origin by design
+  (that is how the tunnel works). Hearth's OAuth Owner approval still
+  gates the MCP endpoint.
+- **Free-tier interstitial.** ngrok shows a browser warning page on HTML
+  traffic; API calls pass through untouched.
+
 ## Tunnels
 
-Hearth does not manage tunnels. Your tunnel or reverse proxy should point to:
+ngrok is the only supported remote path (`hearth serve --ngrok`). The agent
+forwards to:
 
 ```text
 http://127.0.0.1:7176
 ```
 
-Prefer adding an identity-aware proxy in front of public tunnels. Hearth
-OAuth still protects the MCP endpoint, but the tunnel URL should not be
+Hearth OAuth still protects the MCP endpoint, but the tunnel URL should not be
 treated as a secret.
 
 ## Shell Access