@hamedb89/localghost 0.1.10 → 0.1.13

package/docs/flows.md

@@ -5,13 +5,16 @@
 As a developer, I want Localghost to be a drop-in dev dependency so I can add friendly local hostnames without rebuilding the same Caddy and hosts setup in every repo.
 
 ```sh
+npm install -D @hamedb89/localghost
+pnpm add -D @hamedb89/localghost
 yarn add -D @hamedb89/localghost
+bun add -d @hamedb89/localghost
 ```
 
-Then initialize the project contract:
+Choose the install command for the repository's package manager. Then initialize the project contract:
 
 ```sh
-yarn localghost init --write-scripts
+localghost init --write-scripts
 ```
 
 ## Project Contract
@@ -32,7 +35,7 @@ api.app.localhost 8787
 As a developer, I want to know whether my laptop is ready before Localghost changes system files.
 
 ```sh
-yarn localghost doctor
+localghost doctor
 ```
 
 Localghost checks for Caddy and prints the exact install command when it is missing. It does not run Homebrew automatically.
@@ -42,8 +45,8 @@ Localghost checks for Caddy and prints the exact install command when it is miss
 As a developer, I want to know when Localghost itself is stale without paying for a network check on every run.
 
 ```sh
-yarn localghost update
-LOCALGHOST_NO_UPDATE_CHECK=1 yarn localghost doctor
+localghost update
+LOCALGHOST_NO_UPDATE_CHECK=1 localghost doctor
 ```
 
 Localghost checks npm after successful commands, caches the result for 24 hours, and ignores check failures. `LOCALGHOST_NO_UPDATE_CHECK=1` and `--no-update-check` disable the automatic check.
@@ -53,7 +56,7 @@ Localghost checks npm after successful commands, caches the result for 24 hours,
 As a developer, I want one explicit setup command that updates only the managed Localghost block in `/etc/hosts` and validates Caddy.
 
 ```sh
-yarn localghost:setup
+localghost setup
 ```
 
 ## Daily Dev
@@ -61,8 +64,8 @@ yarn localghost:setup
 As a developer, I want a daily command that starts the local HTTP proxy from the same config file, with local HTTPS available only when I ask for it.
 
 ```sh
-yarn localghost:ready
-yarn localghost:proxy
+localghost status --ready
+localghost dev
 ```
 
 Most repos will run this next to their app server, for example Vite on `127.0.0.1:5173`.
@@ -70,7 +73,7 @@ Most repos will run this next to their app server, for example Vite on `127.0.0.
 When a repo really needs local certificates:
 
 ```sh
-yarn localghost:proxy:https
+localghost dev --https
 ```
 
 ## Config Discovery
@@ -78,9 +81,9 @@ yarn localghost:proxy:https
 As a developer, I want Localghost to fit repos that already have naming conventions without hidden file searches.
 
 ```sh
-yarn localghost print --config .localghost.preview
-yarn localghost print --config .localghost.private --config .localghost
-yarn localghost print --config-pattern '^\.localghost\.(private|preview)$'
+localghost print --config .localghost.preview
+localghost print --config .localghost.private --config .localghost
+localghost print --config-pattern '^\.localghost\.(private|preview)$'
 ```
 
 Localghost uses the first existing configured file. Regex discovery scans filenames in the project root.
@@ -90,7 +93,7 @@ Localghost uses the first existing configured file. Regex discovery scans filena
 As a developer, I want to see the local domain layer as a simple `domain -> upstream` map.
 
 ```sh
-yarn localghost routes
+localghost routes
 ```
 
 ```txt
@@ -115,7 +118,7 @@ export default {
 
 The plugin defaults to HTTP. Pass `https: true` only when Vite is expected to sit behind a Caddy HTTPS proxy. Localghost prints URLs but does not open browser tabs.
 
-If `.localghost` is missing, an interactive `yarn dev` asks whether to create it, asks for the primary `.localhost` domain, allows extra domains, explains the `/etc/hosts` password prompt, and runs setup when confirmed. Non-interactive runs fail with the exact setup command instead of guessing.
+If `.localghost` is missing, an interactive development run asks whether to create it, asks for the primary `.localhost` domain, allows extra domains, explains the `/etc/hosts` password prompt, and runs setup when confirmed. Non-interactive runs fail with the exact setup command instead of guessing.
 
 ## Ghost Tunnel
 
@@ -124,13 +127,13 @@ As a production app, I want one opt-in flag that makes `<route>-<project>-<owner
 ```js
 export default defineLocalghostConfig({
   ghostTunnel: {
-    domains: "socialworkouts.app",
+    domains: "moonlit-otter.example",
     mode: "manual"
   }
 });
 ```
 
-The production flow is DNS wildcard -> `constructGhostTunnelUrl` -> deployed app -> app auth -> `assertSecureGhostTunnelRequest`. By default the helper constructs and parses `route`, `project`, and `owner` from the wildcard label before `ghost.<domain>`, requires HTTPS, and requires the app to pass `authenticated: true`. See [Ghost Tunnel](./ghost-tunnel.md).
+The production flow is DNS wildcard -> same-project ingress handler -> `constructGhostTunnelUrl` -> deployed app auth -> `assertSecureGhostTunnelRequest` -> exact `.ghosttunnel` lookup -> transport decision. By default the helper constructs and parses `route`, `project`, and `owner` from the wildcard label before `ghost.<domain>`, requires HTTPS, and requires the app to pass `authenticated: true`. `transport: "none"` stops at ingress plus lookup, `transport: "ip"` accepts a signed direct-address token and redirects to that address plus the exact `.ghosttunnel` port, and `transport: "tunnel"` queues the request through Redis for a local `localghost tunnel` agent. See [Ghost Tunnel](./ghost-tunnel.md).
 
 Relay registration is local-agent-only: signed exact-host claims, explicit local targets, private access by default, no arbitrary URL proxy endpoint, and safe offline behavior when the agent disconnects.
 
@@ -141,8 +144,8 @@ When `ghostTunnel` is configured, route and Vite startup logs print the producti
 As a developer, I want to retest setup without deleting my project config.
 
 ```sh
-yarn localghost reset
-yarn localghost setup
+localghost reset
+localghost setup
 ```
 
 `reset` removes only the managed hosts block, generated Caddyfile, and setup state. It leaves `.localghost` in place.
@@ -152,8 +155,8 @@ yarn localghost setup
 As a developer, I want to cleanly remove Localghost from a project when the repo is archived or no longer needs friendly hostnames.
 
 ```sh
-yarn localghost teardown
-yarn localghost teardown --remove-caddyfile
+localghost teardown
+localghost teardown --remove-caddyfile
 ```
 
 `teardown` removes only the Localghost managed `/etc/hosts` block. The generated Caddyfile is kept unless `--remove-caddyfile` is passed.
@@ -163,8 +166,8 @@ yarn localghost teardown --remove-caddyfile
 As a developer or agent, I want to see what Localghost changed without reading system files directly.
 
 ```sh
-yarn localghost status
-yarn localghost status --json
+localghost status
+localghost status --json
 ```
 
 Localghost records setup and teardown in `ops/local/localghost-state.json`. That file is project-local state, not OS temp state.
@@ -174,9 +177,9 @@ Localghost records setup and teardown in `ops/local/localghost-state.json`. That
 As a Codex or agent user, I want commands that are inspectable and scriptable without opening a browser.
 
 ```sh
-yarn localghost print
-yarn localghost doctor
-yarn localghost update
+localghost print
+localghost doctor
+localghost update
 ```
 
 The CLI reference lives in [localghost(1)](./localghost.1.md). Future flows can add MCP helpers and repo templates, but the base package should remain a small, predictable CLI.

package/docs/ghost-tunnel.md

@@ -9,7 +9,7 @@ Ghost Tunnel is the production-facing Localghost entrypoint for apps that want a
 For Social Workouts, the default namespace is:
 
 ```txt
-<route>-<project>-<owner>.ghost.socialworkouts.app
+<route>-<project>-<owner>.ghost.moonlit-otter.example
 ```
 
 The feature is off by default. Opt in from `localghost.config.mjs`:
@@ -19,8 +19,10 @@ import { defineLocalghostConfig } from "@hamedb89/localghost";
 
 export default defineLocalghostConfig({
   ghostTunnel: {
-    domains: "socialworkouts.app",
-    mode: "manual"
+    domains: "moonlit-otter.example",
+    mode: "manual",
+    adapter: "vercel",
+    transport: "none"
   }
 });
 ```
@@ -30,7 +32,7 @@ With `ghostTunnel: { domains }` in the default manual mode, route output and Vit
 ```txt
 localghost ghost tunnel
   mode: manual
-  expected: https://app-decision-layer-hamed.ghost.socialworkouts.app/
+  expected: https://app-decision-layer-hamed.ghost.moonlit-otter.example/
 ```
 
 Without `domains`, the log keeps the production domain wildcarded with `*`:
@@ -48,7 +50,52 @@ Public mode keeps the namespace flexible unless you configure a preview. This is
 ```txt
 localghost ghost tunnel
   mode: public
-  configured: https://<route>-<project>-<owner>.ghost.socialworkouts.app/
+  configured: https://<route>-<project>-<owner>.ghost.moonlit-otter.example/
+```
+
+The adapter describes where the wildcard ingress runs. The transport describes how that deployed ingress reaches your local machine. The lowest-risk smoke path is the same-project Vercel adapter with no public-to-local transport:
+
+```js
+export default defineLocalghostConfig({
+  ghostTunnel: {
+    domains: "copper-comet.example",
+    mode: "public",
+    requireAuth: false,
+    adapter: {
+      provider: "vercel",
+      strategy: "same-project"
+    },
+    transport: "none"
+  }
+});
+```
+
+`transport: "none"` means the wildcard host is intercepted by the deployed app and resolved against `.ghosttunnel`, but no live public-to-local stream is established yet. This is the right first slice for proving routing, exact-host lookup, and response semantics before adding a real transport.
+
+The split is intentional:
+
+- `adapter`: where ingress lives, for example the same Vercel project or a separate relay app.
+- `transport`: how public traffic gets back to your local machine.
+
+Today `transport: "none"`, `transport: "ip"`, and `transport: "tunnel"` are implemented. The `tunnel` transport is the drop-in shared-state version: deployed ingress queues the request in Redis, the local agent polls that queue, forwards to `127.0.0.1:<port>`, and writes the response back.
+
+`transport: "ip"` is the thinnest direct-address transport. The deployed ingress still validates the ghost host and resolves the exact route from `.ghosttunnel`, but the shared URL also carries a signed IP transport token. The handler then redirects to that address plus the configured local port. This keeps the route and port in repo truth while making the shared address explicit.
+
+For LAN or private-address use, opt in explicitly:
+
+```js
+export default defineLocalghostConfig({
+  ghostTunnel: {
+    domains: "copper-comet.example",
+    mode: "public",
+    requireAuth: false,
+    adapter: "vercel",
+    transport: {
+      kind: "ip",
+      allowPrivateNetworkAddress: true
+    }
+  }
+});
 ```
 
 Use object form to override defaults or provide a concrete preview URL:
@@ -56,7 +103,7 @@ Use object form to override defaults or provide a concrete preview URL:
 ```js
 export default defineLocalghostConfig({
   ghostTunnel: {
-    domains: "socialworkouts.app",
+    domains: "moonlit-otter.example",
     preview: {
       route: "plan",
       project: "summer-base",
@@ -71,16 +118,141 @@ export default defineLocalghostConfig({
 1. Add `ghostTunnel: { domains: "your-domain.com" }`, `ghostTunnel: "manual"`, or `ghostTunnel.preview` to `localghost.config.mjs`.
 2. Point the wildcard DNS record for `*.ghost.<your-domain>` at the deployed app.
 3. Route `*.ghost.<your-domain>` to the same production app that serves the Vite build.
-4. In production request handling, read the Localghost project config without resolving local `.localghost` setup.
-5. Construct tunnel URLs from `route`, `project`, and `owner`.
-6. Validate the incoming request host, protocol, and auth before serving the tunnel surface.
+4. Add a same-project ingress handler that intercepts the wildcard host before the static app shell.
+5. In that handler, read the Localghost project config without resolving local `.localghost` setup.
+6. Construct tunnel URLs from `route`, `project`, and `owner`.
+7. Validate the incoming request host, protocol, and auth before serving the tunnel surface.
+8. For `transport: "tunnel"`, provide Redis REST env vars to the deployed handler and run `localghost tunnel` beside the local dev server.
+
+## Exact Route File
+
+Use `.ghosttunnel` as the exact-host companion to `.localghost`:
+
+```txt
+decisionlayer-decision-layer-hamedbahrami.ghost.copper-comet.example 5173
+notes-decision-layer-hamedbahrami.ghost.copper-comet.example 4173
+```
+
+The format matches `.localghost`: one exact host and one local port per line. Localghost exposes `readGhostTunnelEntries()`, `findGhostTunnelEntry()`, and `resolveGhostTunnelRequest()` so a same-project ingress handler can parse the wildcard host and look up its exact local target without inventing a second config format.
+
+## Same-Project Vercel Handler
+
+For a drop-in Vite app on Vercel, connect `*.ghost.<your-domain>` to the same project, then rewrite ghost hosts into a function instead of the static app:
+
+```json
+{
+  "rewrites": [
+    {
+      "source": "/:path*",
+      "has": [{ "type": "host", "value": "(.*)\\.ghost\\.copper-comet\\.example" }],
+      "destination": "/api/ghost"
+    }
+  ]
+}
+```
+
+Then the handler can resolve the request and return a safe relay status, a signed IP redirect, or a Redis-backed tunnel response:
+
+```ts
+import { createVercelGhostTunnelHandler } from "@hamedb89/localghost";
+
+export default createVercelGhostTunnelHandler({
+  cwd: process.cwd(),
+  domain: "copper-comet.example",
+  authenticated: false,
+  ipSigningSecret: process.env.LOCALGHOST_IP_SIGNING_SECRET
+});
+```
+
+`ipSigningSecret` is only required for `transport: "ip"`. For `transport: "tunnel"`, the handler uses the Redis REST env vars above unless you pass a custom `tunnelStore`.
+
+## Signed IP URLs
+
+Use `constructGhostTunnelIpUrl()` to create a shareable URL for `transport: "ip"`:
+
+```ts
+import { constructGhostTunnelIpUrl } from "@hamedb89/localghost";
+
+const url = constructGhostTunnelIpUrl({
+  domain: "copper-comet.example",
+  route: "decisionlayer",
+  project: "decision-layer",
+  owner: "hamedbahrami",
+  path: "/week/1",
+  address: "203.0.113.10",
+  signingSecret: process.env.LOCALGHOST_IP_SIGNING_SECRET!,
+  ghostTunnel: {
+    mode: "public",
+    domains: "copper-comet.example",
+    transport: "ip"
+  }
+});
+```
+
+That shared URL still uses the wildcard ghost host, but it also carries a signed `__localghost=...` token. The deployed handler verifies that token against the exact ghost host, reads the local port from `.ghosttunnel`, and redirects to the direct address:
+
+```txt
+https://decisionlayer-decision-layer-hamedbahrami.ghost.copper-comet.example/week/1?__localghost=...
+  -> http://203.0.113.10:5173/week/1
+```
+
+This is intentionally simple and explicit:
+
+- the repo owns the route and port through `.ghosttunnel`
+- the shared link owns the direct address
+- the deployed handler only accepts signed IP claims bound to the exact ghost host
+
+It is not a hidden reverse proxy. After redirect, the browser talks directly to the target address.
+
+## Redis Tunnel Transport
+
+Use `transport: "tunnel"` when you want the shared URL to keep going through the deployed Ghost Tunnel host instead of redirecting the browser to a direct IP address:
+
+```js
+export default defineLocalghostConfig({
+  ghostTunnel: {
+    domains: "copper-comet.example",
+    mode: "public",
+    requireAuth: false,
+    adapter: "vercel",
+    transport: {
+      kind: "tunnel",
+      store: {
+        provider: "vercel-redis",
+        env: "auto"
+      }
+    }
+  }
+});
+```
+
+`env: "auto"` reads Redis REST variables from the deployed function environment. The current lookup order is:
+
+```txt
+LOCALGHOST_REDIS_REST_URL / LOCALGHOST_REDIS_REST_TOKEN
+UPSTASH_REDIS_REST_URL / UPSTASH_REDIS_REST_TOKEN
+KV_REST_API_URL / KV_REST_API_TOKEN
+REDIS_REST_API_URL / REDIS_REST_API_TOKEN
+```
+
+For Vercel, add a Redis Marketplace integration to the project and make sure it exposes REST URL/token variables to the Production environment. Legacy Vercel KV REST variables still work, but new projects should treat Redis as the current provider shape.
+
+Run the local agent next to your dev server:
+
+```sh
+localghost tunnel
+```
+
+The agent reads `localghost.config.mjs`, reads exact hosts from `.ghosttunnel`, sends short route heartbeats to Redis, polls for queued requests, and serves them from local ports. It does not open arbitrary targets; each public host must exist in `.ghosttunnel`.
+
+The MVP transport is polling-based and intentionally bounded. It is good for app previews and demos, not large uploads, streaming responses, or high-throughput production traffic. Defaults are a 25 second ingress wait window, 30 second route heartbeat, 60 second request TTL, 1 MiB request body cap, and 5 MiB response body cap. Override those on `transport` only when the app needs it.
 
 ## Vercel DNS
 
 For Vercel, add the Ghost Tunnel wildcard domain to the project first:
 
 ```txt
-*.ghost.decisionlayer.tech
+*.ghost.copper-comet.example
 ```
 
 Then create the DNS record that points that wildcard at the same Vercel project. In Vercel-managed DNS, the record name is relative to the zone:
@@ -109,7 +281,7 @@ Type:  CNAME
 Value: cname.vercel-dns-016.com.
 ```
 
-Do not use only `*` for Ghost Tunnel. A record named `*` covers `anything.decisionlayer.tech`, but Ghost Tunnel URLs look like `decisionlayer-decision-layer-hamed.ghost.decisionlayer.tech`, so the wildcard must live under `ghost`.
+Do not use only `*` for Ghost Tunnel. A record named `*` covers `anything.copper-comet.example`, but Ghost Tunnel URLs look like `decisionlayer-decision-layer-hamed.ghost.copper-comet.example`, so the wildcard must live under `ghost`.
 
 ```ts
 import {
@@ -121,7 +293,7 @@ import {
 const { config } = await readLocalghostProjectConfig();
 
 const url = constructGhostTunnelUrl({
-  domain: "socialworkouts.app",
+  domain: "moonlit-otter.example",
   route: "plan",
   project: "summer-base",
   owner: "hamed",
@@ -130,13 +302,13 @@ const url = constructGhostTunnelUrl({
 
 const route = assertSecureGhostTunnelRequest({
   host: request.headers.get("host") ?? "",
-  domain: "socialworkouts.app",
+  domain: "moonlit-otter.example",
   protocol: request.url.startsWith("https:") ? "https" : "http",
   authenticated: Boolean(session),
   ghostTunnel: config.ghostTunnel
 });
 
-// url is https://plan-summer-base-hamed.ghost.socialworkouts.app/
+// url is https://plan-summer-base-hamed.ghost.moonlit-otter.example/
 // route.namespace is { route: "plan", project: "summer-base", owner: "hamed" }.
 ```
 
@@ -145,7 +317,7 @@ When `ghostTunnel.preview` is configured, Localghost logs the concrete preview U
 ```txt
 localghost ghost tunnel
   mode: manual
-  expected: https://plan-summer-base-hamed.ghost.socialworkouts.app/
+  expected: https://plan-summer-base-hamed.ghost.moonlit-otter.example/
 ```
 
 In an interactive Vite terminal, press `g` to show the Ghost Tunnel configuration and open a numbered concrete URL. Wildcard `*` URLs are shown for observability, but the menu only opens configured concrete domains.
@@ -159,7 +331,7 @@ The default namespace tags are `route`, `project`, and `owner`, joined with `-`.
 ```js
 export default defineLocalghostConfig({
   ghostTunnel: {
-    domains: "socialworkouts.app"
+    domains: "moonlit-otter.example"
   }
 });
 ```
@@ -194,7 +366,7 @@ For custom tags, pass extra values to the constructor:
 
 ```ts
 constructGhostTunnelUrl({
-  domain: "socialworkouts.app",
+  domain: "moonlit-otter.example",
   route: "plan",
   project: "summer-base",
   owner: "hamed",
@@ -209,7 +381,7 @@ constructGhostTunnelUrl({
 
 - `ghostTunnel` is opt-in and resolves to disabled unless the project config enables it.
 - The default production entry host is `ghost.<your-domain>`, with a wildcard of `*.ghost.<your-domain>`.
-- The default wildcard label must be `route-project-owner`, such as `plan-summer-base-hamed.ghost.socialworkouts.app`.
+- The default wildcard label must be `route-project-owner`, such as `plan-summer-base-hamed.ghost.moonlit-otter.example`.
 - The configured spread tag may contain the namespace separator. By default, that is `project`.
 - Other namespace values cannot include the namespace separator, because parsing must be reversible.
 - Host labels must be DNS-safe lowercase ASCII labels after normalization.
@@ -219,7 +391,7 @@ constructGhostTunnelUrl({
 
 ## Relay Security
 
-Localghost relay is private by default. Public requests can select a Ghost Tunnel route, but they must never select the local target URL, hostname, IP, or port. There must be no `/proxy?url=...` style endpoint.
+Localghost relay is private by default. Public requests can select a Ghost Tunnel route, but they must never select an arbitrary local target URL or port. There must be no `/proxy?url=...` style endpoint.
 
 Route registration goes through an authenticated local agent:
 
@@ -230,7 +402,7 @@ import {
 } from "@hamedb89/localghost";
 
 const claim = signRelayRouteClaim({
-  host: "plan-summer-base-hamed.ghost.socialworkouts.app",
+  host: "plan-summer-base-hamed.ghost.moonlit-otter.example",
   scope: "socialworkouts:preview",
   agentId: "local-agent-1",
   expiresAt: new Date(Date.now() + 10 * 60 * 1000).toISOString()
@@ -264,6 +436,20 @@ The relay helpers enforce these rules:
 - `renderRelayOfflineResponse()` returns a safe offline page with no secrets or stack traces.
 - Vite integration continues to generate explicit `allowedHosts`; it never sets `allowedHosts: true`.
 
+For `transport: "ip"`, the handler uses a signed IP token instead of an open target selector:
+
+- `constructGhostTunnelIpUrl()` signs `{ host, address, protocol, expiresAt }`.
+- `resolveGhostTunnelIpRedirect()` rejects tampered, expired, wrong-host, or private-network claims unless private-network IPs are explicitly allowed.
+- The redirect target port still comes from the exact `.ghosttunnel` entry, not from the shared URL.
+
+For `transport: "tunnel"`, the handler uses the shared store instead of a target selector:
+
+- The deployed handler resolves the exact host from `.ghosttunnel`, then checks for a live route heartbeat.
+- The local agent only heartbeats exact hosts from `.ghosttunnel`.
+- Request and response bodies are size-limited and encoded through the store.
+- Hop-by-hop and `x-localghost-*` internal headers are stripped before forwarding.
+- If the route is missing, offline, or times out, the deployed handler returns a safe status page instead of leaking target details.
+
 Run the guardrail tests locally:
 
 ```sh

package/docs/github.md

@@ -4,11 +4,11 @@ Use this copy for the GitHub repo About box, topics, and social cards. Keep it s
 
 ## Repository Description
 
-Friendly local hostnames for app repos. Install the dev dependency, run `yarn dev`, and get clean `.localhost` URLs with Caddy and Vite-safe hosts.
+Friendly local hostnames for app repos. Install with npm, pnpm, Yarn, or Bun and get clean `.localhost` URLs with Caddy and Vite-safe hosts.
 
 Shorter alternative:
 
-Friendly local hostnames for app repos. `yarn add -D`, `yarn dev`, ready.
+Friendly local hostnames for app repos. Add the package, run `localghost`, ready.
 
 ## Topics
 
@@ -62,7 +62,7 @@ After creating `hamedb89/localghost`, this sets the public repo metadata:
 
 ```sh
 gh repo edit hamedb89/localghost \
-  --description "Friendly local hostnames for app repos. Install the dev dependency, run yarn dev, and get clean .localhost URLs with Caddy and Vite-safe hosts." \
+  --description "Friendly local hostnames for app repos. Install with npm, pnpm, Yarn, or Bun and get clean .localhost URLs with Caddy and Vite-safe hosts." \
   --homepage "https://hamedb89.github.io/localghost/" \
   --add-topic localhost \
   --add-topic local-development \
@@ -81,7 +81,7 @@ gh repo edit hamedb89/localghost \
 The first visible paragraph should make the entrypoint feel obvious before it gets into configuration:
 
 ```txt
-Localghost is a tiny Node.js CLI for friendly local domains in app repos. Add it as a dev dependency, run `yarn dev`, and use `http://app.localhost/` instead of remembering which localhost port belongs to which process.
+Localghost is a tiny Node.js CLI for friendly local domains in app repos. Add it with your package manager, run `localghost`, and use `http://app.localhost/` instead of remembering which localhost port belongs to which process.
 ```
 
 Then the next docs layer can explain `.localghost`, Caddy, `/etc/hosts`, Vite `allowedHosts`, and configuration options.

package/docs/localghost.1.md

@@ -7,6 +7,7 @@ localghost - friendly local hostnames for app repos
 ## Synopsis
 
 ```sh
+localghost [--cwd path] [--dry-run]
 localghost init [--write-scripts] [--config file] [--host host] [--port port]
 localghost doctor
 localghost setup [--project name] [--config file] [--config-pattern regex] [--https|--ssl]
@@ -15,12 +16,26 @@ localghost reset [--project name]
 localghost teardown [--project name] [--remove-caddyfile]
 localghost status [--ready] [--json]
 localghost ps [--json]
+localghost tunnel [--cwd path] [--config file] [--config-pattern regex] [--ghost-config file] [--target-host host]
 localghost update [--json]
-localghost dev [--config file] [--config-pattern regex] [--https|--ssl] [--setup] [--trust]
-localghost run [--config file] [--config-pattern regex] [--https|--ssl] [--setup] [--trust] [--dynamic-port] -- command
+localghost dev [--config file] [--config-pattern regex] [--https|--ssl] [--auto-repair yes|no] [--trust]
+localghost run [--config file] [--config-pattern regex] [--https|--ssl] [--auto-repair yes|no] [--trust] [--dynamic-port] -- command
 localghost print [--config file] [--config-pattern regex]
 ```
 
+With no subcommand, Localghost detects npm, pnpm, Yarn, or Bun from `packageManager` or a lockfile, prefers a non-recursive `dev:raw` script, falls back to `dev`, and runs the result through the normal Caddy lifecycle. `--dry-run` prints the detected command without checking or changing machine setup. Set `command: ["<package-manager>", "dev:web"]` in `localghost.config.mjs` when inference should be explicit.
+
+For multiple independently started applications, configure `services` in `localghost.config.mjs`. Each service declares a unique name and host plus its project-relative working directory, requested port, and optional command. Bare `localghost` starts one Caddy process and all service commands, passes service-specific `LOCALGHOST_PORT`, `VITE_PORT`, and `LOCALGHOST_SERVICE` variables, and stops the group when any process exits.
+
+```js
+export default {
+  services: [
+    { name: "web", cwd: "apps/web", host: "xyz.localhost", port: 5173 },
+    { name: "api", cwd: "apps/api", host: "api.xyz.localhost", port: 8787 }
+  ]
+};
+```
+
 ## Description
 
 Localghost reads `.localghost`, optionally reads `localghost.config.mjs`, writes a managed `/etc/hosts` block, records `ops/local/localghost-state.json`, generates `ops/local/Caddyfile`, and runs a Caddy local proxy. The project name is derived from `package.json`, port `5173` is the fallback, HTTP is the default, dynamic ports are on by default, and local HTTPS is explicit with `--https`, `--ssl`, or `https: true` in `localghost.config.mjs`. It is intentionally small and explicit: no hidden installs, no full hosts-file rewrites, no surprise browser tabs, and no broad Vite `allowedHosts: true` shortcut.
@@ -48,7 +63,7 @@ Options:
 - `--port <number>`: primary app port.
 - `--api-host <host>`: API hostname.
 - `--api-port <number>`: API port.
-- `--package-manager <npm|yarn|pnpm>`: package manager for suggested commands.
+- `--package-manager <npm|pnpm|yarn|bun>`: package manager for suggested commands.
 - `--write-scripts`: add Localghost scripts to `package.json`.
 - `--force`: overwrite an existing config file.
 
@@ -78,6 +93,15 @@ Validates the HTTPS Caddyfile and runs `caddy trust --config <Caddyfile>` so bro
 localghost trust
 ```
 
+### repair
+
+Reconciles the managed hosts block, regenerates and validates the Caddyfile, and refreshes project setup state. Use `--https --trust` to also re-run Caddy's local certificate trust step.
+
+```sh
+localghost repair
+localghost repair --https --trust
+```
+
 ### teardown
 
 Removes the managed Localghost block from `/etc/hosts` for the selected project and records the action in `ops/local/localghost-state.json`. It leaves `ops/local/Caddyfile` in place unless `--remove-caddyfile` is passed.
@@ -112,6 +136,16 @@ localghost ps
 localghost ps --json
 ```
 
+### tunnel
+
+Runs the local Ghost Tunnel agent for `ghostTunnel.transport: "tunnel"`. The command reads the Localghost project config, reads exact public hosts from `.ghosttunnel`, sends route heartbeats to the configured Redis REST store, polls for queued requests, and serves them from the matching local port.
+
+```sh
+localghost tunnel
+```
+
+Use `--ghost-config <file>` when the exact route file is not `.ghosttunnel`. Use `--target-host <host>` when the local app listens somewhere other than `127.0.0.1`.
+
 ### update
 
 Checks npm for a newer Localghost release. Pass `--json` for scripts and agents.
@@ -130,7 +164,7 @@ localghost routes
 
 ### dev
 
-Requires setup to be ready, writes `ops/local/Caddyfile`, validates it, and runs Caddy. Supports `--config` and `--config-pattern`. HTTP is the default. Pass `--https` or `--ssl` to run a local HTTPS proxy. Pass `--setup` to explicitly allow `dev` to run setup first when setup is missing or stale. Pass `--trust` to force the Caddy trust step before the proxy stays running.
+Performs a read-only readiness check, repairs stale setup when needed, writes and validates `ops/local/Caddyfile`, and runs Caddy. Supports `--config` and `--config-pattern`. HTTP is the default. Pass `--https` or `--ssl` to run a local HTTPS proxy, `--auto-repair=no` for strict failure behavior, or `--trust` to force the Caddy trust step before the proxy stays running.
 
 ```sh
 localghost dev
@@ -146,13 +180,15 @@ localghost run --trust -- vite
 localghost run --dynamic-port=no -- vite
 ```
 
-By default, Localghost starts at the configured port and walks upward until `127.0.0.1:<port>` is free. Pass `--dynamic-port=no` when you want strict fixed-port behavior. Pass `--setup` to explicitly allow setup when the hosts block is missing or stale.
+By default, Localghost starts at the configured port and walks upward until `127.0.0.1:<port>` is free. It performs a read-only readiness check and repairs stale setup before starting the child. Pass `--dynamic-port=no` for strict fixed-port behavior or `--auto-repair=no` to fail instead of repairing.
 
-When `localghost.config.mjs` exists, `run`, `dev`, `setup`, `status`, `routes`, and the Vite plugin use it as an override layer. Most repos can skip it; add it only for decisions like `https: true`, `dynamicPort: false`, `wwwAlias: false`, custom ports, explicit project names, or the production `ghostTunnel` opt-in.
+When `localghost.config.mjs` exists, `run`, `dev`, `setup`, `status`, `routes`, and the Vite plugin use it as an override layer. Most repos can skip it; add it only for decisions like `https: true`, `dynamicPort: false`, `autoRepair: false`, `wwwAlias: false`, custom ports, explicit project names, or the production `ghostTunnel` opt-in.
 
 `ghostTunnel` does not change local Caddy or `/etc/hosts` setup. It marks `<route>-<project>-<owner>.ghost.<domain>` as a production app entrypoint. Use `ghostTunnel: { domains: "example.com", mode: "manual" }` when the production base domain is known, or omit `domains` to keep logs wildcarded as `https://<route>-<project>-<owner>.ghost.*/`. Production code can call `readLocalghostProjectConfig()`, `constructGhostTunnelUrl()`, and `assertSecureGhostTunnelRequest()` to read the flag, construct default tunnel URLs, validate the wildcard host shape, require HTTPS by default, and require an app-authenticated request by default.
 
-Relay helpers are private by default. Registration requires an authenticated local-agent bearer token plus an exact signed route claim. Targets must be explicit local host/port objects, dangerous ports are blocked, private/LAN targets require explicit opt-in, internal and hop-by-hop headers are stripped, sensitive logs are redacted, and offline agents get a safe 503 page.
+`ghostTunnel.transport` is separate from the deployment adapter. `transport: "none"` proves ingress and exact-route lookup without forwarding. `transport: "ip"` signs a direct address into the shared URL, verifies that token against the exact ghost host, and redirects to the signed address plus the local port from `.ghosttunnel`. `transport: "tunnel"` uses Redis REST env vars plus `localghost tunnel` to queue deployed requests for a local agent. For LAN or private-address IP redirects, set `transport: { kind: "ip", allowPrivateNetworkAddress: true }` explicitly.
+
+Relay helpers are private by default. Registration requires an authenticated local-agent bearer token plus an exact signed route claim. Targets must be explicit local host/port objects, dangerous ports are blocked, private/LAN targets require explicit opt-in, internal and hop-by-hop headers are stripped, sensitive logs are redacted, and offline agents get a safe 503 page. The IP transport follows the same posture: the shared URL carries only a signed `{ host, address, protocol, expiresAt }` claim, while the redirect port still comes from the exact `.ghosttunnel` entry.
 
 When `ghostTunnel` is configured, route output and Vite startup logs print the production URL shape. Manual mode can fill local defaults for `route`, `project`, and `owner`; public mode leaves those slots as `<route>`, `<project>`, and `<owner>` unless `ghostTunnel.preview` pins a concrete URL. Add `ghostTunnel.domains` to fill one or more production base domains. When `ghostTunnel.preview` is configured with `route`, `project`, and `owner`, logs print the concrete URL, inheriting `ghostTunnel.domains` unless `preview.domain` is set. In an interactive Vite terminal, press `g` to show Ghost Tunnel configuration and open a numbered concrete URL.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hamedb89/localghost",
-  "version": "0.1.10",
+  "version": "0.1.13",
   "description": "Friendly local hostnames for app repos with .localghost, Caddy, /etc/hosts, and Vite.",
   "type": "module",
   "bin": {
@@ -45,6 +45,7 @@
     "macos:widget:build": "bash apps/macos-widget/build.sh",
     "dev": "tsx src/cli.ts",
     "test": "npm run build && node --test tests/*.test.mjs",
+    "test:e2e": "npm run build && node --test tests/e2e/*.test.mjs",
     "test:coverage": "npm run build && LOCALGHOST_TEST_SOURCE=1 node --import tsx --test --experimental-test-coverage --test-coverage-include=src/relay.ts --test-coverage-include=src/tunnel.ts --test-coverage-lines=90 --test-coverage-branches=75 --test-coverage-functions=100 tests/*.test.mjs",
     "test:cli": "npm run build && node --test tests/cli.test.mjs",
     "typecheck": "tsc --noEmit",