feat: add optional public funnel exposure

Author: dasomji

README.md

@@ -29,15 +29,18 @@ Use it when your dev server is running on a remote machine and you want to open
 - Supports `--tailscale-port` when you want the MagicDNS URL to include a specific HTTPS port.
 - Detects Laravel + Vite dev output, exposes both servers, rewrites Laravel's `public/hot` file to the Tailscale Vite URL, and proxies Vite assets with CORS headers so module scripts can load cross-origin.
 - Uses a stable alternate Tailscale HTTPS port by default: first free port from `8443` upward.
-- Cleans up the Tailscale Serve mappings it created when the child command exits or you press `Ctrl+C`.
+- Stays private to your tailnet by default.
+- Supports `--public` / `--funnel` for intentional public internet sharing through Tailscale Funnel.
+- Cleans up the Tailscale Serve/Funnel mappings it created when the child command exits or you press `Ctrl+C`.
 
 ## Requirements
 
 - Node.js 20 or newer.
 - Tailscale installed and available as `tailscale` on `PATH`.
 - The device must be logged into Tailscale.
 - Tailscale Serve must be available for the device/tailnet.
-- Your user must be allowed to update Tailscale Serve config. If `tailscale serve` says access is denied, run this once:
+- For `--public`, Tailscale Funnel must be enabled for the device/tailnet.
+- Your user must be allowed to update Tailscale Serve/Funnel config. If `tailscale serve` or `tailscale funnel` says access is denied, run this once:
 
   ```bash
   sudo tailscale set --operator=$USER
@@ -48,9 +51,11 @@ Check Tailscale before using `lizardtail`:
 ```bash
 tailscale status
 tailscale serve --help
+# Optional, only for --public:
+tailscale funnel --help
 ```
 
-`lizardtail` exposes services to your private tailnet via Tailscale Serve. It does **not** use Tailscale Funnel and does not publish your server to the public internet.
+`lizardtail` exposes services to your private tailnet via Tailscale Serve by default. It only uses Tailscale Funnel, which publishes to the public internet, when you explicitly pass `--public` or `--funnel`.
 
 ## Installation
 
@@ -107,6 +112,7 @@ lizardtail -- npm run dev -- --host 0.0.0.0
 | `--timeout <ms>` | `30000` | How long to wait for a port to appear in command output. |
 | `--tailscale-port <port>` | first free `8443+` | Expose the main app on this Tailscale HTTPS port and print it in the MagicDNS URL. Alias: `--https-port`. |
 | `--vite-tailscale-port <port>` | first free `8443+` | Expose a detected Laravel Vite asset server on this Tailscale HTTPS port. Alias: `--vite-https-port`. |
+| `--public`, `--funnel` | disabled | Use Tailscale Funnel for public internet access instead of private tailnet-only Serve. |
 | `--no-open-check` | enabled | Skip waiting for the local port to accept connections before calling Tailscale. |
 | `-h`, `--help` | | Show help. |
 
@@ -183,6 +189,28 @@ If your app server lands on a known port and you only want to expose that server
 lizardtail --port 8001 composer run dev
 ```
 
+### Public internet sharing
+
+By default, URLs are only reachable from devices in your tailnet. To intentionally publish through Tailscale Funnel:
+
+```bash
+lizardtail --public pnpm dev
+```
+
+or:
+
+```bash
+lizardtail --funnel pnpm dev
+```
+
+This prints a public HTTPS URL such as:
+
+```text
+https://my-host.tailabc.ts.net:8443
+```
+
+Use this only for apps you are comfortable exposing publicly. Stop `lizardtail` with `Ctrl+C` to remove the Funnel mapping it created.
+
 ### Longer startup timeout
 
 ```bash
@@ -196,18 +224,20 @@ lizardtail --timeout 60000 pnpm dev
 3. It scans recent output for a local port.
 4. Once it finds a port, it waits for `127.0.0.1:<port>` or the configured `--host` to accept connections.
 5. It chooses the first free Tailscale HTTPS port from `8443` upward, unless `--tailscale-port` was provided.
-6. It runs:
+6. It runs Tailscale Serve for private tailnet-only access:
 
    ```bash
    tailscale serve --bg --https <tailscale-port> http://<host>:<port>
    ```
 
-   On older Tailscale versions, if that form fails for `127.0.0.1`/`localhost`, it falls back to:
+   With `--public` / `--funnel`, it runs Tailscale Funnel for public internet access:
 
    ```bash
-   tailscale serve --bg --https <tailscale-port> <port>
+   tailscale funnel --bg --https <tailscale-port> http://<host>:<port>
    ```
 
+   On older Tailscale versions, if that form fails for `127.0.0.1`/`localhost`, it falls back to the same command with just `<port>` as the target.
+
 7. It reads `tailscale status --json`, extracts the current device's MagicDNS name, and prints:
 
    ```text
@@ -216,10 +246,12 @@ lizardtail --timeout 60000 pnpm dev
 
 ## Shutdown behavior
 
-When the child command exits, or when you press `Ctrl+C`, `lizardtail` removes the Tailscale Serve mappings it created for that run:
+When the child command exits, or when you press `Ctrl+C`, `lizardtail` removes the Tailscale mappings it created for that run:
 
 ```bash
 tailscale serve --https=<port> off
+# or, with --public:
+tailscale funnel --https=<port> off
 ```
 
 It only tracks ports created by the current `lizardtail` process.

src/index.ts

@@ -18,6 +18,7 @@ export interface Options {
   viteTailscalePort?: number;
   timeoutMs: number;
   openCheck: boolean;
+  public: boolean;
 }
 
 export const DEFAULT_TIMEOUT_MS = 30_000;
@@ -36,13 +37,15 @@ Options:
                        Expose the main app on this Tailscale HTTPS port. Default: first free ${DEFAULT_TAILSCALE_HTTPS_PORT}+ port.
   --vite-tailscale-port <port>
                        Expose a detected Laravel Vite server on this Tailscale HTTPS port.
+  --public, --funnel   Expose publicly on the internet with Tailscale Funnel instead of private tailnet-only Serve.
   --no-open-check      Skip waiting for the local port to accept connections.
   -h, --help           Show this help.
 
 Examples:
   lizardtail pnpm dev
   lizardtail --port 3000 npm run dev
   lizardtail --tailscale-port 8450 pnpm dev
+  lizardtail --public pnpm dev
 `);
 }
 
@@ -57,6 +60,7 @@ export function parseArgs(argv: string[]): Options {
     host: "127.0.0.1",
     timeoutMs: DEFAULT_TIMEOUT_MS,
     openCheck: true,
+    public: false,
   };
 
   for (let i = 0; i < argv.length; i += 1) {
@@ -77,6 +81,11 @@ export function parseArgs(argv: string[]): Options {
       continue;
     }
 
+    if (arg === "--public" || arg === "--funnel") {
+      options.public = true;
+      continue;
+    }
+
     if (arg === "--port") {
       const value = argv[++i];
       if (!value) usage();
@@ -283,18 +292,17 @@ function isTailscaleServePermissionError(error: unknown): boolean {
   return message.includes("access denied") && (message.includes("sudo tailscale serve") || message.includes("operator"));
 }
 
-function tailscaleServeCommand(target: string, tailscalePort?: number): string[] {
-  const args = ["serve", "--bg"];
-  if (tailscalePort !== undefined) args.push("--https", String(tailscalePort));
-  args.push(target);
-  return args;
+type ExposureMode = "serve" | "funnel";
+
+function tailscaleExposeCommand(target: string, tailscalePort: number, mode: ExposureMode): string[] {
+  return [mode, "--bg", "--https", String(tailscalePort), target];
 }
 
 function tailscaleUrl(dnsName: string, tailscalePort?: number): string {
   return tailscalePort === undefined ? `https://${dnsName}` : `https://${dnsName}:${tailscalePort}`;
 }
 
-function tailscaleServePermissionHelp(target: string, tailscalePort?: number): string {
+function tailscaleServePermissionHelp(target: string, tailscalePort: number, mode: ExposureMode): string {
   return `Tailscale refused to update Serve config without elevated privileges.
 
 Run this once to let your user manage Tailscale Serve:
@@ -305,7 +313,7 @@ Then rerun lizardtail.
 
 Or expose this server manually with:
 
-  sudo tailscale ${tailscaleServeCommand(target, tailscalePort).join(" ")}`;
+  sudo tailscale ${tailscaleExposeCommand(target, tailscalePort, mode).join(" ")}`;
 }
 
 async function exec(command: string, args: string[], opts: { input?: string; env?: NodeJS.ProcessEnv } = {}): Promise<{ stdout: string; stderr: string }> {
@@ -508,28 +516,30 @@ function corsHeaders(): Record<string, string> {
 interface TailscaleExposure {
   url: string;
   httpsPort: number;
+  mode: ExposureMode;
 }
 
-async function exposeWithTailscaleDetailed(host: string, port: number, tailscalePort?: number): Promise<TailscaleExposure> {
+async function exposeWithTailscaleDetailed(host: string, port: number, tailscalePort?: number, publicExposure = false): Promise<TailscaleExposure> {
   await exec("tailscale", ["status"]);
 
   const target = `http://${host}:${port}`;
   const resolvedTailscalePort = await resolveTailscaleHttpsPort(target, tailscalePort);
+  const mode: ExposureMode = publicExposure ? "funnel" : "serve";
 
   try {
-    await exec("tailscale", tailscaleServeCommand(target, resolvedTailscalePort));
+    await exec("tailscale", tailscaleExposeCommand(target, resolvedTailscalePort, mode));
   } catch (firstError) {
     if (isTailscaleServePermissionError(firstError)) {
-      throw new Error(tailscaleServePermissionHelp(target, resolvedTailscalePort));
+      throw new Error(tailscaleServePermissionHelp(target, resolvedTailscalePort, mode));
     }
 
     if (host !== "127.0.0.1" && host !== "localhost") throw firstError;
 
     try {
-      await exec("tailscale", tailscaleServeCommand(String(port), resolvedTailscalePort));
+      await exec("tailscale", tailscaleExposeCommand(String(port), resolvedTailscalePort, mode));
     } catch (fallbackError) {
       if (isTailscaleServePermissionError(fallbackError)) {
-        throw new Error(tailscaleServePermissionHelp(target, resolvedTailscalePort));
+        throw new Error(tailscaleServePermissionHelp(target, resolvedTailscalePort, mode));
       }
       throw fallbackError;
     }
@@ -539,20 +549,20 @@ async function exposeWithTailscaleDetailed(host: string, port: number, tailscale
   const status = JSON.parse(stdout) as { Self?: { DNSName?: string; TailscaleIPs?: string[] } };
   const dnsName = status.Self?.DNSName?.replace(/\.$/, "");
 
-  if (dnsName) return { url: tailscaleUrl(dnsName, resolvedTailscalePort), httpsPort: resolvedTailscalePort };
+  if (dnsName) return { url: tailscaleUrl(dnsName, resolvedTailscalePort), httpsPort: resolvedTailscalePort, mode };
 
   const ip = status.Self?.TailscaleIPs?.find((value) => /^\d+\.\d+\.\d+\.\d+$/.test(value));
-  if (ip) return { url: tailscaleUrl(ip, resolvedTailscalePort), httpsPort: resolvedTailscalePort };
+  if (ip) return { url: tailscaleUrl(ip, resolvedTailscalePort), httpsPort: resolvedTailscalePort, mode };
 
   throw new Error("could not determine this device's Tailscale DNS name or IP");
 }
 
-export async function exposeWithTailscale(host: string, port: number, tailscalePort?: number): Promise<string> {
-  return (await exposeWithTailscaleDetailed(host, port, tailscalePort)).url;
+export async function exposeWithTailscale(host: string, port: number, tailscalePort?: number, publicExposure = false): Promise<string> {
+  return (await exposeWithTailscaleDetailed(host, port, tailscalePort, publicExposure)).url;
 }
 
-async function removeTailscaleServePort(port: number): Promise<void> {
-  await exec("tailscale", ["serve", `--https=${port}`, "off"]);
+async function removeTailscaleExposurePort(port: number, mode: ExposureMode): Promise<void> {
+  await exec("tailscale", [mode, `--https=${port}`, "off"]);
 }
 
 export async function main(): Promise<void> {
@@ -576,15 +586,15 @@ export async function main(): Promise<void> {
   let exposing: Promise<void> | undefined;
   let recentOutput = "";
   let detectionTimer: NodeJS.Timeout | undefined;
-  const createdTailscalePorts = new Set<number>();
+  const createdTailscalePorts = new Map<number, ExposureMode>();
 
   const cleanupTailscaleServe = async () => {
-    for (const port of createdTailscalePorts) {
+    for (const [port, mode] of createdTailscalePorts) {
       try {
-        await removeTailscaleServePort(port);
-        console.error(`lizardtail: removed Tailscale Serve mapping on HTTPS port ${port}`);
+        await removeTailscaleExposurePort(port, mode);
+        console.error(`lizardtail: removed Tailscale ${mode === "funnel" ? "Funnel" : "Serve"} mapping on HTTPS port ${port}`);
       } catch (error) {
-        console.error(`lizardtail: failed to remove Tailscale Serve mapping on HTTPS port ${port}: ${errorMessage(error)}`);
+        console.error(`lizardtail: failed to remove Tailscale ${mode === "funnel" ? "Funnel" : "Serve"} mapping on HTTPS port ${port}: ${errorMessage(error)}`);
       }
     }
     createdTailscalePorts.clear();
@@ -601,8 +611,8 @@ export async function main(): Promise<void> {
       const localUrl = `http://${options.host}:${port}`;
       console.error(`\nlizardtail: detected local server on ${localUrl}`);
       if (options.openCheck) await waitForOpenPort(options.host, port, 10_000);
-      const exposure = await exposeWithTailscaleDetailed(options.host, port, options.tailscalePort);
-      createdTailscalePorts.add(exposure.httpsPort);
+      const exposure = await exposeWithTailscaleDetailed(options.host, port, options.tailscalePort, options.public);
+      createdTailscalePorts.set(exposure.httpsPort, exposure.mode);
       console.error(`lizardtail: serving via Tailscale: ${exposure.url}\n`);
     })().catch((error: unknown) => {
       console.error(`lizardtail: failed to expose server: ${errorMessage(error)}`);
@@ -625,12 +635,12 @@ export async function main(): Promise<void> {
         await waitForOpenPort(viteHost, vitePort, 10_000);
       }
 
-      const appExposure = await exposeWithTailscaleDetailed(options.host, appPort, options.tailscalePort);
-      createdTailscalePorts.add(appExposure.httpsPort);
+      const appExposure = await exposeWithTailscaleDetailed(options.host, appPort, options.tailscalePort, options.public);
+      createdTailscalePorts.set(appExposure.httpsPort, appExposure.mode);
       const viteProxy = await startCorsProxy(viteHost, vitePort);
       const viteTailscalePort = options.viteTailscalePort ?? (await chooseTailscaleHttpsPort(appExposure.httpsPort));
-      const viteExposure = await exposeWithTailscaleDetailed(viteProxy.host, viteProxy.port, viteTailscalePort);
-      createdTailscalePorts.add(viteExposure.httpsPort);
+      const viteExposure = await exposeWithTailscaleDetailed(viteProxy.host, viteProxy.port, viteTailscalePort, options.public);
+      createdTailscalePorts.set(viteExposure.httpsPort, viteExposure.mode);
       const hotPath = await writeLaravelHotFile(viteExposure.url);
 
       console.error(`lizardtail: serving Laravel via Tailscale: ${appExposure.url}`);

tests/index.test.ts

@@ -61,6 +61,7 @@ test("parseArgs parses options before the command", () => {
     port: 3000,
     timeoutMs: 5000,
     openCheck: false,
+    public: false,
   });
 });
 
@@ -70,6 +71,7 @@ test("parseArgs keeps command flags after -- delimiter", () => {
     host: "127.0.0.1",
     timeoutMs: 1000,
     openCheck: true,
+    public: false,
   });
 });
 
@@ -79,6 +81,7 @@ test("parseArgs uses documented defaults", () => {
     host: "127.0.0.1",
     timeoutMs: DEFAULT_TIMEOUT_MS,
     openCheck: true,
+    public: false,
   });
 });
 
@@ -90,6 +93,17 @@ test("parseArgs supports explicit Tailscale HTTPS ports", () => {
     viteTailscalePort: 8453,
     timeoutMs: DEFAULT_TIMEOUT_MS,
     openCheck: true,
+    public: false,
+  });
+});
+
+test("parseArgs supports public Funnel exposure", () => {
+  assert.deepEqual(parseArgs(["--public", "pnpm", "dev"]), {
+    command: ["pnpm", "dev"],
+    host: "127.0.0.1",
+    timeoutMs: DEFAULT_TIMEOUT_MS,
+    openCheck: true,
+    public: true,
   });
 });
 
@@ -136,6 +150,53 @@ exit 1
   }
 });
 
+test("exposeWithTailscale can expose publicly with Tailscale Funnel", async () => {
+  const tempDir = await mkdtemp(path.join(tmpdir(), "lizardtail-test-"));
+  const tailscalePath = path.join(tempDir, "tailscale");
+  const tailscaleLog = path.join(tempDir, "tailscale.log");
+  const originalPath = process.env.PATH;
+
+  await writeFile(
+    tailscalePath,
+    `#!/usr/bin/env bash
+printf '%s\n' "$*" >> "$TAILSCALE_LOG"
+if [ "$1" = "status" ] && [ "$2" = "--json" ]; then
+  echo '{"Self":{"DNSName":"test-host.tailnet.ts.net."}}'
+  exit 0
+fi
+if [ "$1" = "status" ]; then
+  echo 'ok'
+  exit 0
+fi
+if [ "$1" = "serve" ] && [ "$2" = "status" ] && [ "$3" = "--json" ]; then
+  echo '{}'
+  exit 0
+fi
+if [ "$1" = "funnel" ]; then
+  echo 'funnel ok'
+  exit 0
+fi
+exit 1
+`,
+    { mode: 0o755 },
+  );
+
+  try {
+    process.env.PATH = `${tempDir}${path.delimiter}${originalPath ?? ""}`;
+    process.env.TAILSCALE_LOG = tailscaleLog;
+
+    const url = await exposeWithTailscale("127.0.0.1", 3001, undefined, true);
+
+    assert.equal(url, "https://test-host.tailnet.ts.net:8443");
+    const calls = await readFile(tailscaleLog, "utf8");
+    assert.match(calls, /funnel --bg --https 8443 http:\/\/127\.0\.0\.1:3001/);
+  } finally {
+    process.env.PATH = originalPath;
+    delete process.env.TAILSCALE_LOG;
+    await rm(tempDir, { recursive: true, force: true });
+  }
+});
+
 test("exposeWithTailscale auto-selects a port when default HTTPS already serves another target", async () => {
   const tempDir = await mkdtemp(path.join(tmpdir(), "lizardtail-test-"));
   const tailscalePath = path.join(tempDir, "tailscale");