@sunshinelife83/hearth 1.0.0 → 1.1.0

package/docs/setup.md

@@ -11,10 +11,12 @@ This guide covers ChatGPT and Coding Agents using Hearth with local projects.
 - a public HTTPS URL that forwards to the local Hearth server, only when
   ChatGPT will connect
 
-Hearth does not create the public tunnel for you. ChatGPT users need a public
-HTTPS URL forwarding to the local server: their own reverse proxy or tunnel,
-or Hearth's relay-free direct exposure (own domain + TLS, see
-`hearth expose`).
+ChatGPT users need a public HTTPS URL forwarding to the local server. The
+supported way is the managed ngrok tunnel:
+
+1. **Managed per-PC tunnel (the only remote path):** `hearth ngrok setup`
+   saves this PC's static domain — see
+   [Managed Tunnel](#managed-tunnel-every-pc-is-server-url-and-tunnel).
 
 ## Install And Configure
 
@@ -71,28 +73,18 @@ These commands do not require `hearth serve`.
 
 ### Connect ChatGPT
 
-Setup only asks for a public URL if you selected ChatGPT. Start your tunnel or
-reverse proxy first and point it at:
+Setup only asks for a public URL if you selected ChatGPT. Enter your static
+ngrok domain as the public origin without `/mcp` (run
+`hearth ngrok setup` first if you have not saved one yet):
 
 ```text
-http://127.0.0.1:7176
-```
-
-Proxy the whole Hearth server from the root path of your tunnel or reverse
-proxy — never mount only `/mcp`. Hearth also serves OAuth discovery and
-authorization routes outside `/mcp`, and a path-scoped mount can strip `/mcp`
-before the request reaches Hearth (arriving as `/` and failing).
-
-Enter the public origin without `/mcp`:
-
-```text
-https://your-tunnel-host.example.com
+https://xxx.ngrok-free.dev
 ```
 
 Configure the MCP client with the full MCP endpoint:
 
 ```text
-https://your-tunnel-host.example.com/mcp
+https://xxx.ngrok-free.dev/mcp
 ```
 
 Protocol compatibility is automatic. Hearth serves MCP 2026-07-28 requests
@@ -106,19 +98,56 @@ A Coding Agents-only setup skips this section.
 Run:
 
 ```bash
-npx @sunshinelife83/hearth serve
+npx @sunshinelife83/hearth serve --ngrok
 ```
 
-If your tunnel URL changes, update the persisted value before starting:
+The static domain never changes, so no URL resync is ever needed. If you
+replace the domain, update the persisted value before starting:
 
 ```bash
-npx @sunshinelife83/hearth config set publicBaseUrl https://hearth.example.com
-npx @sunshinelife83/hearth serve
+npx @sunshinelife83/hearth ngrok setup --domain https://new-domain.ngrok-free.dev
+npx @sunshinelife83/hearth serve --ngrok
 ```
 
 Use the origin only — never append `/mcp` to `publicBaseUrl`. The client URL is
 `<origin>/mcp`. `hearth doctor --fix` repairs a saved `/mcp` suffix.
 
+## Managed Tunnel: Every PC Is Server, URL, And Tunnel
+
+`hearth ngrok setup` binds this PC to its static ngrok domain, so
+`hearth serve --ngrok` alone is server + stable public URL + tunnel. No
+second terminal, no pasted tunnel URLs, no hostname churn on restart.
+
+Prerequisites (once per PC):
+
+- an ngrok account (free is enough — every account gets one stable dev
+  domain such as `xxx.ngrok-free.dev`)
+- `ngrok` installed (`brew install ngrok`, the Linux package for your
+  distro, or `winget install --id Ngrok.ngrok`)
+- `ngrok config add-authtoken <your-token>` completed once (token from
+  https://dashboard.ngrok.com/get-started/your-authtoken)
+
+Then:
+
+```bash
+hearth ngrok setup --domain xxx.ngrok-free.dev
+hearth serve --ngrok
+hearth ngrok status
+```
+
+What setup does: saves the static domain, syncs `server.publicBaseUrl`, and
+enables `server.trustProxy` so rate limits see real client IPs. Your
+authtoken stays in ngrok's own config — Hearth never stores it. Scripted
+setups can pass `--yes` (requires `--domain`).
+
+`hearth serve --ngrok` supervises the ngrok agent and fails fast if the live
+domain drifts from the saved one, instead of serving locally-but-dark.
+`hearth doctor` checks the binary, auth, domain match, and child liveness.
+Plain `hearth serve` stays local-only.
+
+Note: ngrok free shows a browser interstitial page on HTML traffic. API calls
+are unaffected; the Owner approval page needs one click-through.
+
 ## Connect A Host (ChatGPT / Claude / Generic)
 
 Run:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sunshinelife83/hearth",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "description": "Expose a secure local coding workspace through an MCP server.",
   "keywords": [],
   "homepage": "https://github.com/Waishnav/hearth#readme",

package/schema/v1/hearth.schema.json

@@ -429,39 +429,22 @@
       },
       "additionalProperties": false
     },
-    "tls": {
+    "tunnel": {
       "default": {
-        "certFile": null,
-        "keyFile": null,
-        "acmeDir": null
+        "provider": "none",
+        "domain": null
       },
       "type": "object",
       "properties": {
-        "certFile": {
-          "default": null,
-          "anyOf": [
-            {
-              "type": "string",
-              "minLength": 1
-            },
-            {
-              "type": "null"
-            }
-          ]
-        },
-        "keyFile": {
-          "default": null,
-          "anyOf": [
-            {
-              "type": "string",
-              "minLength": 1
-            },
-            {
-              "type": "null"
-            }
+        "provider": {
+          "default": "none",
+          "type": "string",
+          "enum": [
+            "none",
+            "ngrok"
           ]
         },
-        "acmeDir": {
+        "domain": {
           "default": null,
           "anyOf": [
             {