fix: bind loopback by address and pin the sandbox port so containers work

Two defaults that each break the Inspector inside a container.

#1951 — the web UI never loads in a VS Code dev container. `HOST` defaulted
to the NAME `localhost`, and `server.listen(port, host)` resolves a name
through `dns.lookup` and binds the SINGLE address it gets back. Since Node 17
the default result order is `verbatim`, so on a glibc Linux host — whose
/etc/hosts maps localhost to both 127.0.0.1 and ::1 — that is `::1`. The
server bound IPv6 loopback only and refused every IPv4 client, including the
dev container port forwarder. It presents as an endless spinner rather than a
connection error because the forwarder accepts on the host side before failing
to connect inward. Default to the ADDRESS 127.0.0.1 instead; an explicit
HOST=localhost is still honored as typed.

#2008 — the Apps tab is unreachable in any container. The MCP Apps sandbox
listened on an OS-assigned port, so it changed every run and could never be
named in a devcontainer `forwardPorts`, a `docker run -p`, or a tunnel. Default
it to a fixed 6275, mirroring CLIENT_PORT's fixed 6274, and retry once on an
OS-assigned port (loudly) if it is taken — the collision a dynamic default
never had.

Verified in the reporter's exact image
(mcr.microsoft.com/devcontainers/typescript-node:4-24-trixie): both listeners
come up on 127.0.0.1 and answer 200 on 6274 and 6275/sandbox.

Also EXPOSE 6275 and set MCP_SANDBOX_PORT in the image, and document both
defaults in the web README, the migration guide, and the root README's Docker
section.

Signed-off-by: cliffhall <cliff@futurescale.com>

clients/web/server/resolve-bind-host.ts

@@ -26,21 +26,46 @@ function isEnabled(value: string | undefined): boolean {
   return v === "true" || v === "1";
 }
 
+/**
+ * The default bind host: the IPv4 loopback **address**, deliberately not the
+ * name `localhost`.
+ *
+ * `server.listen(port, host)` resolves a name through `dns.lookup` and binds the
+ * **single** address it gets back. Since Node 17 the default result order is
+ * `verbatim`, so Node takes whatever the resolver returns first rather than
+ * preferring IPv4 — and on a glibc Linux host with the stock `/etc/hosts`
+ * (`127.0.0.1 localhost` *and* `::1 localhost`) that is `::1`. `HOST=localhost`
+ * therefore binds IPv6 loopback **only**, and every IPv4 client is refused.
+ *
+ * That is invisible on a desktop, where the browser resolves `localhost` the
+ * same way and lands on `::1` too. It breaks wherever the connection is made by
+ * something that pins IPv4 `127.0.0.1` instead — a VS Code dev container's port
+ * forwarder (#1951), an `ssh -L …:127.0.0.1:…` tunnel, a container healthcheck.
+ * Binding the address directly removes the resolver from the decision, and the
+ * loopback origin allow-list already covers `localhost`, `127.0.0.1`, and
+ * `[::1]` alike, so browsing to `http://localhost:PORT` still works (browsers
+ * fall back across address families; a Node `listen` does not).
+ */
+export const DEFAULT_BIND_HOST = "127.0.0.1";
+
 /**
  * Resolve the bind hostname from `env` (default `process.env`), defaulting to
- * `localhost`. Refuses an all-interfaces host (`0.0.0.0` / `::` / empty / their
- * legacy spellings) unless {@link BIND_ALL_INTERFACES_ENV} is explicitly
- * enabled — the published Docker image sets it, since a container must bind
- * `0.0.0.0` to be reachable through `-p`. Throws (fail fast, loudly) rather than
- * silently binding wide open. The returned value is trimmed and de-bracketed
- * (an IPv6 literal is returned bare, e.g. `HOST=[::1]` → `::1`) so detection,
- * `listen()`, and the origin list all consume the same value; `formatHostForUrl`
- * re-adds the brackets wherever a URL is built.
+ * {@link DEFAULT_BIND_HOST}. Refuses an all-interfaces host (`0.0.0.0` / `::` /
+ * empty / their legacy spellings) unless {@link BIND_ALL_INTERFACES_ENV} is
+ * explicitly enabled — the published Docker image sets it, since a container
+ * must bind `0.0.0.0` to be reachable through `-p`. Throws (fail fast, loudly)
+ * rather than silently binding wide open. The returned value is trimmed and
+ * de-bracketed (an IPv6 literal is returned bare, e.g. `HOST=[::1]` → `::1`) so
+ * detection, `listen()`, and the origin list all consume the same value;
+ * `formatHostForUrl` re-adds the brackets wherever a URL is built.
+ *
+ * An explicit `HOST=localhost` is honored as typed — the single-family bind
+ * described on {@link DEFAULT_BIND_HOST} is then the caller's choice, not ours.
  */
 export function resolveBindHostname(
   env: NodeJS.ProcessEnv = process.env,
 ): string {
-  const host = (env.HOST ?? "localhost").trim();
+  const host = (env.HOST ?? DEFAULT_BIND_HOST).trim();
   if (isAllInterfacesHost(host) && !isEnabled(env[BIND_ALL_INTERFACES_ENV])) {
     // Show the resolved address when it differs from the typed spelling — the
     // guard now catches forms the resolver folds to the wildcard (a fullwidth

clients/web/server/sandbox-controller.ts

@@ -11,13 +11,14 @@ import {
   canonicalUrlHost,
   isAllInterfacesHost,
 } from "../../../core/node/hostUrl.ts";
+import { DEFAULT_BIND_HOST } from "./resolve-bind-host.js";
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 
 export interface SandboxControllerOptions {
   /** Port to bind (0 = dynamic). */
   port: number;
-  /** Host to bind (default localhost). */
+  /** Host to bind (default {@link DEFAULT_BIND_HOST}). */
   host?: string;
   /**
    * The backend's origin allow-list (the embedder origins). Used to build the
@@ -95,10 +96,28 @@ function parseListenPort(raw: string | undefined): number | undefined {
 }
 
 /**
- * Resolve sandbox port from env: MCP_SANDBOX_PORT → SERVER_PORT → 0 (dynamic).
- * An invalid value falls through rather than crashing the boot; a set-but-invalid
- * MCP_SANDBOX_PORT (the dedicated knob) is warned so the fall-through isn't
- * silent — matching the warn-and-drop precedent for ALLOWED_ORIGINS.
+ * The default sandbox listen port — **fixed**, deliberately not `0`.
+ *
+ * A `0` default lets the OS assign, which is fine on a desktop (the browser
+ * learns the port from `/api/config`) but unusable anywhere the port has to be
+ * declared *before* the process starts: a dev container's `forwardPorts`, a
+ * `docker run -p`, a k8s service, an SSH tunnel. The port changed on every run,
+ * so it could never be named in that config and the Apps tab was unreachable
+ * (#2008). `CLIENT_PORT` has always defaulted to a fixed `6274` for the same
+ * reason; this is its sandbox counterpart.
+ *
+ * `6275` sits next to the web port so the pair is easy to forward together. It
+ * is not a v1 carry-over — v2 has no proxy server on it.
+ */
+export const DEFAULT_SANDBOX_PORT = 6275;
+
+/**
+ * Resolve sandbox port from env: MCP_SANDBOX_PORT → SERVER_PORT →
+ * {@link DEFAULT_SANDBOX_PORT}. An invalid value falls through rather than
+ * crashing the boot; a set-but-invalid MCP_SANDBOX_PORT (the dedicated knob) is
+ * warned so the fall-through isn't silent — matching the warn-and-drop
+ * precedent for ALLOWED_ORIGINS. An explicit `0` is still honored as "let the
+ * OS assign" ({@link parseListenPort} accepts it).
  */
 export function resolveSandboxPort(): number {
   const fromSandbox = parseListenPort(process.env.MCP_SANDBOX_PORT);
@@ -107,13 +126,21 @@ export function resolveSandboxPort(): number {
       `Ignoring invalid MCP_SANDBOX_PORT="${process.env.MCP_SANDBOX_PORT}" (need an integer 0–65535); falling back.`,
     );
   }
-  return fromSandbox ?? parseListenPort(process.env.SERVER_PORT) ?? 0;
+  return (
+    fromSandbox ??
+    parseListenPort(process.env.SERVER_PORT) ??
+    DEFAULT_SANDBOX_PORT
+  );
 }
 
 export function createSandboxController(
   options: SandboxControllerOptions,
 ): SandboxController {
-  const { port, host = "localhost", allowedOrigins } = options;
+  // Defaulted to the same address the web server binds, never the name
+  // `localhost` — a name resolves to one address family and would reintroduce
+  // the #1951 split (web on IPv4, sandbox on IPv6) for any future call site
+  // that omits `host`. Both call sites pass `config.sandboxHost` today.
+  const { port, host = DEFAULT_BIND_HOST, allowedOrigins } = options;
   let server: Server | null = null;
   let sandboxUrl: string | null = null;
 
@@ -177,8 +204,28 @@ export function createSandboxController(
           });
           res.end(sandboxHtml);
         });
+        // A taken port used to mean "no sandbox at all", which was tolerable
+        // only because the default was dynamic and therefore never collided.
+        // Now that it's fixed (see DEFAULT_SANDBOX_PORT), a second Inspector —
+        // or anything else already on 6275 — would take the Apps tab down, so
+        // retry once on an OS-assigned port. The retry is announced loudly:
+        // whoever pinned MCP_SANDBOX_PORT to forward it needs to know the pin
+        // didn't take, and a silently-moved port is exactly the failure this
+        // default was introduced to fix.
+        let retriedDynamic = false;
         server.on("error", (err: NodeJS.ErrnoException) => {
           if (err.code === "EADDRINUSE") {
+            if (!retriedDynamic && port !== 0) {
+              retriedDynamic = true;
+              console.warn(
+                `Sandbox: port ${port} in use; falling back to an OS-assigned port. ` +
+                  `The MCP Apps tab will work locally, but the sandbox is no longer ` +
+                  `on a predictable port — set MCP_SANDBOX_PORT to a free one if you ` +
+                  `need to forward it (container / SSH tunnel / reverse proxy).`,
+              );
+              server!.listen(0, host);
+              return;
+            }
             console.error(
               `Sandbox: port ${port || "dynamic"} in use. MCP Apps tab may not work.`,
             );