feat: support explicit tailscale https port

Author: dasomji

README.md

@@ -24,6 +24,7 @@ Use it when your dev server is running on a remote machine and you want to open
 - Runs `tailscale serve --bg http://127.0.0.1:<port>`.
 - Prints the HTTPS MagicDNS URL for the current Tailscale device.
 - Supports an explicit `--port` when automatic detection is not possible.
+- Supports `--tailscale-port` when you want the MagicDNS URL to include a specific HTTPS port.
 
 ## Requirements
 
@@ -99,6 +100,7 @@ lizardtail -- npm run dev -- --host 0.0.0.0
 | `--port <port>` | auto-detect | Expose this port instead of reading one from command output. |
 | `--host <host>` | `127.0.0.1` | Local host to pass to Tailscale Serve. |
 | `--timeout <ms>` | `30000` | How long to wait for a port to appear in command output. |
+| `--tailscale-port <port>` | `443` | Expose on this Tailscale HTTPS port and print it in the MagicDNS URL. Alias: `--https-port`. |
 | `--no-open-check` | enabled | Skip waiting for the local port to accept connections before calling Tailscale. |
 | `-h`, `--help` | | Show help. |
 
@@ -128,6 +130,26 @@ lizardtail -- npm run dev -- --host 0.0.0.0
 lizardtail --port 3000 npm run dev
 ```
 
+### MagicDNS URL with an explicit port
+
+By default, Tailscale Serve uses HTTPS port 443, so the URL has no port:
+
+```text
+https://my-host.tailabc.ts.net
+```
+
+If you want a URL with a port, choose the Tailscale HTTPS port separately:
+
+```bash
+lizardtail --tailscale-port 8450 pnpm dev
+```
+
+That prints a URL like:
+
+```text
+https://my-host.tailabc.ts.net:8450
+```
+
 ### Longer startup timeout
 
 ```bash
@@ -146,6 +168,12 @@ lizardtail --timeout 60000 pnpm dev
    tailscale serve --bg http://<host>:<port>
    ```
 
+   If `--tailscale-port <port>` is set, it runs:
+
+   ```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:
 
    ```bash

src/index.ts

@@ -11,6 +11,7 @@ export interface Options {
   command: string[];
   host: string;
   port?: number;
+  tailscalePort?: number;
   timeoutMs: number;
   openCheck: boolean;
 }
@@ -25,12 +26,15 @@ Options:
   --port <port>        Expose this port instead of detecting one from output.
   --host <host>        Local host to expose. Default: 127.0.0.1
   --timeout <ms>       Port-detection timeout. Default: ${DEFAULT_TIMEOUT_MS}
+  --tailscale-port <port>
+                       Expose on this Tailscale HTTPS port instead of 443.
   --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
 `);
 }
 
@@ -89,6 +93,23 @@ export function parseArgs(argv: string[]): Options {
       continue;
     }
 
+    if (arg === "--tailscale-port" || arg === "--https-port") {
+      const value = argv[++i];
+      if (!value) usage();
+      options.tailscalePort = parsePort(value);
+      continue;
+    }
+
+    if (arg.startsWith("--tailscale-port=")) {
+      options.tailscalePort = parsePort(arg.slice("--tailscale-port=".length));
+      continue;
+    }
+
+    if (arg.startsWith("--https-port=")) {
+      options.tailscalePort = parsePort(arg.slice("--https-port=".length));
+      continue;
+    }
+
     if (arg === "--timeout") {
       const value = argv[++i];
       if (!value) usage();
@@ -166,7 +187,18 @@ function isTailscaleServePermissionError(error: unknown): boolean {
   return message.includes("access denied") && (message.includes("sudo tailscale serve") || message.includes("operator"));
 }
 
-function tailscaleServePermissionHelp(target: string): string {
+function tailscaleServeCommand(target: string, tailscalePort?: number): string[] {
+  const args = ["serve", "--bg"];
+  if (tailscalePort !== undefined) args.push("--https", String(tailscalePort));
+  args.push(target);
+  return args;
+}
+
+function tailscaleUrl(dnsName: string, tailscalePort?: number): string {
+  return tailscalePort === undefined ? `https://${dnsName}` : `https://${dnsName}:${tailscalePort}`;
+}
+
+function tailscaleServePermissionHelp(target: string, tailscalePort?: number): string {
   return `Tailscale refused to update Serve config without elevated privileges.
 
 Run this once to let your user manage Tailscale Serve:
@@ -177,7 +209,7 @@ Then rerun lizardtail.
 
 Or expose this server manually with:
 
-  sudo tailscale serve --bg ${target}`;
+  sudo tailscale ${tailscaleServeCommand(target, tailscalePort).join(" ")}`;
 }
 
 async function exec(command: string, args: string[], opts: { input?: string } = {}): Promise<{ stdout: string; stderr: string }> {
@@ -239,24 +271,24 @@ export async function waitForOpenPort(host: string, port: number, timeoutMs: num
   throw new Error(`timed out waiting for ${host}:${port} to accept connections`);
 }
 
-export async function exposeWithTailscale(host: string, port: number): Promise<string> {
+export async function exposeWithTailscale(host: string, port: number, tailscalePort?: number): Promise<string> {
   await exec("tailscale", ["status"]);
 
   const target = `http://${host}:${port}`;
   try {
-    await exec("tailscale", ["serve", "--bg", target]);
+    await exec("tailscale", tailscaleServeCommand(target, tailscalePort));
   } catch (firstError) {
     if (isTailscaleServePermissionError(firstError)) {
-      throw new Error(tailscaleServePermissionHelp(target));
+      throw new Error(tailscaleServePermissionHelp(target, tailscalePort));
     }
 
     if (host !== "127.0.0.1" && host !== "localhost") throw firstError;
 
     try {
-      await exec("tailscale", ["serve", "--bg", String(port)]);
+      await exec("tailscale", tailscaleServeCommand(String(port), tailscalePort));
     } catch (fallbackError) {
       if (isTailscaleServePermissionError(fallbackError)) {
-        throw new Error(tailscaleServePermissionHelp(target));
+        throw new Error(tailscaleServePermissionHelp(target, tailscalePort));
       }
       throw fallbackError;
     }
@@ -266,10 +298,10 @@ export async function exposeWithTailscale(host: string, port: number): Promise<s
   const status = JSON.parse(stdout) as { Self?: { DNSName?: string; TailscaleIPs?: string[] } };
   const dnsName = status.Self?.DNSName?.replace(/\.$/, "");
 
-  if (dnsName) return `https://${dnsName}`;
+  if (dnsName) return tailscaleUrl(dnsName, tailscalePort);
 
   const ip = status.Self?.TailscaleIPs?.find((value) => /^\d+\.\d+\.\d+\.\d+$/.test(value));
-  if (ip) return `https://${ip}`;
+  if (ip) return tailscaleUrl(ip, tailscalePort);
 
   throw new Error("could not determine this device's Tailscale DNS name or IP");
 }
@@ -298,7 +330,7 @@ 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 tailscaleUrl = await exposeWithTailscale(options.host, port);
+      const tailscaleUrl = await exposeWithTailscale(options.host, port, options.tailscalePort);
       console.error(`lizardtail: serving via Tailscale: ${tailscaleUrl}\n`);
     })().catch((error: unknown) => {
       console.error(`lizardtail: failed to expose server: ${errorMessage(error)}`);

tests/index.test.ts

@@ -58,6 +58,59 @@ test("parseArgs uses documented defaults", () => {
   });
 });
 
+test("parseArgs supports an explicit Tailscale HTTPS port", () => {
+  assert.deepEqual(parseArgs(["--tailscale-port", "8450", "pnpm", "dev"]), {
+    command: ["pnpm", "dev"],
+    host: "127.0.0.1",
+    tailscalePort: 8450,
+    timeoutMs: DEFAULT_TIMEOUT_MS,
+    openCheck: true,
+  });
+});
+
+test("exposeWithTailscale can expose on an explicit Tailscale HTTPS port", 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" ]; then
+  echo 'serve 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, 8450);
+
+    assert.equal(url, "https://test-host.tailnet.ts.net:8450");
+    const calls = await readFile(tailscaleLog, "utf8");
+    assert.match(calls, /serve --bg --https 8450 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 explains how to fix Tailscale Serve permission errors", async () => {
   const tempDir = await mkdtemp(path.join(tmpdir(), "lizardtail-test-"));
   const tailscalePath = path.join(tempDir, "tailscale");