programbo · programbo · May 28, 2026
diff --git a/REMOTE.md b/REMOTE.md
@@ -89,8 +89,17 @@ For hosted web pairing over Tailscale HTTPS, opt in to Tailscale Serve:
 npx t3 serve --tailscale-serve
 ```
 
-By default this configures Tailscale Serve on HTTPS port 443 and advertises
-`https://machine.tailnet.ts.net/`. Advanced users can choose a different HTTPS port:
+By default this configures Tailscale Serve on HTTPS port 443, discovers the machine's MagicDNS
+name, and advertises `https://machine.tailnet.ts.net/`. If MagicDNS discovery is unavailable, the
+CLI falls back to the normal headless pairing URL.
+
+Use `--tailscale-serve-host` when the advertised HTTPS host should be fixed instead of discovered:
+
+```bash
+npx t3 serve --tailscale-serve --tailscale-serve-host machine.tailnet.ts.net
+```
+
+Advanced users can also choose a different HTTPS port:
 
 ```bash
 npx t3 serve --tailscale-serve --tailscale-serve-port 8443

diff --git a/apps/server/src/cli/config.test.ts b/apps/server/src/cli/config.test.ts
@@ -75,6 +75,7 @@ it.layer(NodeServices.layer)("cli config resolution", (it) => {
           logWebSocketEvents: Option.none(),
           tailscaleServeEnabled: Option.none(),
           tailscaleServePort: Option.none(),
+          tailscaleServeHost: Option.none(),
         },
         Option.none(),
       ).pipe(
@@ -92,6 +93,7 @@ it.layer(NodeServices.layer)("cli config resolution", (it) => {
                   T3CODE_NO_BROWSER: "true",
                   T3CODE_AUTO_BOOTSTRAP_PROJECT_FROM_CWD: "false",
                   T3CODE_LOG_WS_EVENTS: "true",
+                  T3CODE_TAILSCALE_SERVE_HOST: "env-tailnet.example.ts.net",
                 },
               }),
             ),
@@ -118,6 +120,7 @@ it.layer(NodeServices.layer)("cli config resolution", (it) => {
         logWebSocketEvents: true,
         tailscaleServeEnabled: false,
         tailscaleServePort: 443,
+        tailscaleServeHost: "env-tailnet.example.ts.net",
       });
     }),
   );
@@ -141,6 +144,7 @@ it.layer(NodeServices.layer)("cli config resolution", (it) => {
           logWebSocketEvents: Option.some(true),
           tailscaleServeEnabled: Option.some(true),
           tailscaleServePort: Option.some(8443),
+          tailscaleServeHost: Option.some("cli-tailnet.example.ts.net"),
         },
         Option.some("Debug"),
       ).pipe(
@@ -158,6 +162,7 @@ it.layer(NodeServices.layer)("cli config resolution", (it) => {
                   T3CODE_NO_BROWSER: "false",
                   T3CODE_AUTO_BOOTSTRAP_PROJECT_FROM_CWD: "false",
                   T3CODE_LOG_WS_EVENTS: "false",
+                  T3CODE_TAILSCALE_SERVE_HOST: "ignored-env-tailnet.example.ts.net",
                 },
               }),
             ),
@@ -184,6 +189,7 @@ it.layer(NodeServices.layer)("cli config resolution", (it) => {
         logWebSocketEvents: true,
         tailscaleServeEnabled: true,
         tailscaleServePort: 8443,
+        tailscaleServeHost: "cli-tailnet.example.ts.net",
       });
     }),
   );
@@ -215,6 +221,7 @@ it.layer(NodeServices.layer)("cli config resolution", (it) => {
           logWebSocketEvents: Option.some(false),
           tailscaleServeEnabled: Option.none(),
           tailscaleServePort: Option.none(),
+          tailscaleServeHost: Option.none(),
         },
         Option.none(),
       ).pipe(
@@ -253,6 +260,7 @@ it.layer(NodeServices.layer)("cli config resolution", (it) => {
         logWebSocketEvents: false,
         tailscaleServeEnabled: false,
         tailscaleServePort: 443,
+        tailscaleServeHost: undefined,
       });
     }),
   );
@@ -290,6 +298,7 @@ it.layer(NodeServices.layer)("cli config resolution", (it) => {
           logWebSocketEvents: Option.none(),
           tailscaleServeEnabled: Option.none(),
           tailscaleServePort: Option.none(),
+          tailscaleServeHost: Option.none(),
         },
         Option.none(),
       ).pipe(
@@ -327,6 +336,7 @@ it.layer(NodeServices.layer)("cli config resolution", (it) => {
         logWebSocketEvents: false,
         tailscaleServeEnabled: false,
         tailscaleServePort: 443,
+        tailscaleServeHost: undefined,
       });
       assert.equal(join(baseDir, "userdata"), resolved.stateDir);
     }),
@@ -353,6 +363,7 @@ it.layer(NodeServices.layer)("cli config resolution", (it) => {
           logWebSocketEvents: Option.none(),
           tailscaleServeEnabled: Option.none(),
           tailscaleServePort: Option.none(),
+          tailscaleServeHost: Option.none(),
         },
         Option.none(),
       ).pipe(
@@ -412,6 +423,7 @@ it.layer(NodeServices.layer)("cli config resolution", (it) => {
           logWebSocketEvents: Option.none(),
           tailscaleServeEnabled: Option.none(),
           tailscaleServePort: Option.none(),
+          tailscaleServeHost: Option.none(),
         },
         Option.some("Debug"),
       ).pipe(
@@ -452,6 +464,7 @@ it.layer(NodeServices.layer)("cli config resolution", (it) => {
         logWebSocketEvents: true,
         tailscaleServeEnabled: false,
         tailscaleServePort: 443,
+        tailscaleServeHost: undefined,
       });
     }),
   );
@@ -488,6 +501,7 @@ it.layer(NodeServices.layer)("cli config resolution", (it) => {
           logWebSocketEvents: Option.none(),
           tailscaleServeEnabled: Option.none(),
           tailscaleServePort: Option.none(),
+          tailscaleServeHost: Option.none(),
         },
         Option.none(),
       ).pipe(
@@ -521,6 +535,7 @@ it.layer(NodeServices.layer)("cli config resolution", (it) => {
         logWebSocketEvents: false,
         tailscaleServeEnabled: false,
         tailscaleServePort: 443,
+        tailscaleServeHost: undefined,
       });
     }),
   );
@@ -545,6 +560,7 @@ it.layer(NodeServices.layer)("cli config resolution", (it) => {
           logWebSocketEvents: Option.none(),
           tailscaleServeEnabled: Option.none(),
           tailscaleServePort: Option.none(),
+          tailscaleServeHost: Option.none(),
         },
         Option.none(),
         {
@@ -584,6 +600,7 @@ it.layer(NodeServices.layer)("cli config resolution", (it) => {
         logWebSocketEvents: false,
         tailscaleServeEnabled: false,
         tailscaleServePort: 443,
+        tailscaleServeHost: undefined,
       });
     }),
   );

diff --git a/apps/server/src/cli/config.ts b/apps/server/src/cli/config.ts
@@ -80,6 +80,10 @@ export const tailscaleServePortFlag = Flag.integer("tailscale-serve-port").pipe(
   Flag.withDescription("HTTPS port for Tailscale Serve when --tailscale-serve is enabled."),
   Flag.optional,
 );
+export const tailscaleServeHostFlag = Flag.string("tailscale-serve-host").pipe(
+  Flag.withDescription("Host name for Tailscale Serve when --tailscale-serve is enabled."),
+  Flag.optional,
+);
 
 const EnvServerConfig = Config.all({
   logLevel: Config.logLevel("T3CODE_LOG_LEVEL").pipe(Config.withDefault("Info")),
@@ -136,6 +140,10 @@ const EnvServerConfig = Config.all({
     Config.option,
     Config.map(Option.getOrUndefined),
   ),
+  tailscaleServeHost: Config.string("T3CODE_TAILSCALE_SERVE_HOST").pipe(
+    Config.option,
+    Config.map(Option.getOrUndefined),
+  ),
 });
 
 export interface CliServerFlags {
@@ -151,6 +159,7 @@ export interface CliServerFlags {
   readonly logWebSocketEvents: Option.Option<boolean>;
   readonly tailscaleServeEnabled: Option.Option<boolean>;
   readonly tailscaleServePort: Option.Option<number>;
+  readonly tailscaleServeHost: Option.Option<string>;
 }
 
 export interface CliAuthLocationFlags {
@@ -185,6 +194,7 @@ export const sharedServerCommandFlags = {
   logWebSocketEvents: logWebSocketEventsFlag,
   tailscaleServeEnabled: tailscaleServeFlag,
   tailscaleServePort: tailscaleServePortFlag,
+  tailscaleServeHost: tailscaleServeHostFlag,
 } as const;
 
 export const authLocationFlags = sharedServerLocationFlags;
@@ -230,6 +240,7 @@ export const resolveServerConfig = (
       logWebSocketEvents: flags.logWebSocketEvents ?? Option.none(),
       tailscaleServeEnabled: flags.tailscaleServeEnabled ?? Option.none(),
       tailscaleServePort: flags.tailscaleServePort ?? Option.none(),
+      tailscaleServeHost: flags.tailscaleServeHost ?? Option.none(),
     } satisfies CliServerFlags;
     const bootstrapFd = Option.getOrUndefined(normalizedFlags.bootstrapFd) ?? env.bootstrapFd;
     const bootstrapEnvelope =
@@ -330,6 +341,13 @@ export const resolveServerConfig = (
       ),
       () => 443,
     );
+    const tailscaleServeHost = Option.getOrElse(
+      resolveOptionPrecedence(
+        normalizedFlags.tailscaleServeHost,
+        Option.fromUndefinedOr(env.tailscaleServeHost),
+      ),
+      () => undefined,
+    );
     const staticDir = devUrl ? undefined : yield* resolveStaticDir();
     const host = Option.getOrElse(
       resolveOptionPrecedence(
@@ -374,6 +392,7 @@ export const resolveServerConfig = (
       logWebSocketEvents,
       tailscaleServeEnabled,
       tailscaleServePort,
+      tailscaleServeHost,
     };
 
     return config;
@@ -397,6 +416,7 @@ export const resolveCliAuthConfig = (
       logWebSocketEvents: Option.none(),
       tailscaleServeEnabled: Option.none(),
       tailscaleServePort: Option.none(),
+      tailscaleServeHost: Option.none(),
     },
     cliLogLevel,
   );

diff --git a/apps/server/src/config.ts b/apps/server/src/config.ts
@@ -73,6 +73,7 @@ export interface ServerConfigShape extends ServerDerivedPaths {
   readonly logWebSocketEvents: boolean;
   readonly tailscaleServeEnabled: boolean;
   readonly tailscaleServePort: number;
+  readonly tailscaleServeHost?: string | undefined;
 }
 
 export const deriveServerPaths = Effect.fn(function* (
@@ -168,6 +169,7 @@ export class ServerConfig extends Context.Service<ServerConfig, ServerConfigShap
           logWebSocketEvents: false,
           tailscaleServeEnabled: false,
           tailscaleServePort: 443,
+          tailscaleServeHost: undefined,
           port: 0,
           host: undefined,
           desktopBootstrapToken: undefined,

diff --git a/apps/server/src/server.ts b/apps/server/src/server.ts
@@ -36,6 +36,7 @@ import { TerminalManagerLive } from "./terminal/Layers/Manager.ts";
 import * as GitManager from "./git/GitManager.ts";
 import { KeybindingsLive } from "./keybindings.ts";
 import { ServerRuntimeStartup, ServerRuntimeStartupLive } from "./serverRuntimeStartup.ts";
+import { TailscaleServeRuntime, TailscaleServeRuntimeLive } from "./tailscaleServeRuntime.ts";
 import { OrchestrationReactorLive } from "./orchestration/Layers/OrchestrationReactor.ts";
 import { RuntimeReceiptBusLive } from "./orchestration/Layers/RuntimeReceiptBus.ts";
 import { ProviderRuntimeIngestionLive } from "./orchestration/Layers/ProviderRuntimeIngestion.ts";
@@ -352,9 +353,11 @@ export const makeServerLayer = Layer.unwrap(
       ? Layer.effectDiscard(
           Effect.acquireRelease(
             Effect.gen(function* () {
+              const tailscaleServeRuntime = yield* TailscaleServeRuntime;
               const server = yield* HttpServer.HttpServer;
               const address = server.address;
               if (typeof address === "string" || !("port" in address)) {
+                yield* tailscaleServeRuntime.markUnavailable;
                 return null;
               }
 
@@ -365,18 +368,24 @@ export const makeServerLayer = Layer.unwrap(
                 localHost: "127.0.0.1",
               }).pipe(
                 Effect.as({ localPort, servePort: config.tailscaleServePort }),
+                Effect.tap(() => tailscaleServeRuntime.markConfigured),
                 Effect.tap(() =>
                   Effect.logInfo("Tailscale Serve configured", {
                     localPort,
                     servePort: config.tailscaleServePort,
                   }),
                 ),
                 Effect.catch((cause) =>
-                  Effect.logWarning("Failed to configure Tailscale Serve", {
-                    cause,
-                    localPort,
-                    servePort: config.tailscaleServePort,
-                  }).pipe(Effect.as(null)),
+                  tailscaleServeRuntime.markUnavailable.pipe(
+                    Effect.andThen(
+                      Effect.logWarning("Failed to configure Tailscale Serve", {
+                        cause,
+                        localPort,
+                        servePort: config.tailscaleServePort,
+                      }),
+                    ),
+                    Effect.as(null),
+                  ),
                 ),
               );
             }),
@@ -411,6 +420,7 @@ export const makeServerLayer = Layer.unwrap(
 
     return serverApplicationLayer.pipe(
       Layer.provideMerge(RuntimeServicesLive),
+      Layer.provideMerge(TailscaleServeRuntimeLive),
       Layer.provideMerge(HttpServerLive),
       Layer.provide(ObservabilityLive),
       Layer.provideMerge(FetchHttpClient.layer),

diff --git a/apps/server/src/serverRuntimeStartup.ts b/apps/server/src/serverRuntimeStartup.ts
@@ -38,6 +38,7 @@ import {
   formatHostForUrl,
   isWildcardHost,
   issueHeadlessServeAccessInfo,
+  resolveAdvertisedStartupBaseUrl,
 } from "./startupAccess.ts";
 
 export class ServerRuntimeStartupError extends Data.TaggedError("ServerRuntimeStartupError")<{
@@ -247,7 +248,13 @@ const resolveStartupBrowserTarget = Effect.gen(function* () {
     serverConfig.host && !isWildcardHost(serverConfig.host)
       ? `http://${formatHostForUrl(serverConfig.host)}:${serverConfig.port}`
       : localUrl;
-  const baseTarget = serverConfig.devUrl?.toString() ?? bindUrl;
+  const httpBaseTarget = serverConfig.devUrl?.toString() ?? bindUrl;
+  const baseTarget = yield* resolveAdvertisedStartupBaseUrl({
+    httpBaseUrl: httpBaseTarget,
+    tailscaleServeEnabled: serverConfig.tailscaleServeEnabled,
+    tailscaleServePort: serverConfig.tailscaleServePort,
+    tailscaleServeHost: serverConfig.tailscaleServeHost,
+  });
   return yield* Effect.succeed(serverConfig.mode === "desktop" ? baseTarget : undefined).pipe(
     Effect.flatMap((target) =>
       target ? Effect.succeed(target) : serverAuth.issueStartupPairingUrl(baseTarget),