diff --git a/apps/app/src/lib/dev-websocket-url.test.ts b/apps/app/src/lib/dev-websocket-url.test.ts
index b8c5ecb0de..e01783eae9 100644
--- a/apps/app/src/lib/dev-websocket-url.test.ts
+++ b/apps/app/src/lib/dev-websocket-url.test.ts
@@ -7,6 +7,7 @@ function installWindowLocation(url: string): void {
     location: {
       host: location.host,
       hostname: location.hostname,
+      port: location.port,
       protocol: location.protocol,
     },
   });
@@ -19,6 +20,7 @@ describe("buildDevWebSocketUrl", () => {
 
   it("connects directly to the backend for HTTP source dev", () => {
     vi.stubGlobal("__BB_DEV_WS_BROWSER_HOST_PORT__", 23_802);
+    vi.stubGlobal("__BB_DEV_APP_BROWSER_HOST_PORT__", 15_802);
     installWindowLocation("http://devbox.local:15802/threads/thr_1");
 
     expect(buildDevWebSocketUrl({ path: "/ws" })).toBe(
@@ -28,6 +30,7 @@ describe("buildDevWebSocketUrl", () => {
 
   it("uses the proxied app origin for HTTPS bb connect shares", () => {
     vi.stubGlobal("__BB_DEV_WS_BROWSER_HOST_PORT__", 23_802);
+    vi.stubGlobal("__BB_DEV_APP_BROWSER_HOST_PORT__", 15_802);
     installWindowLocation(
       "https://sawyer--15802.getbb.app/threads/thr_jew2ruik89",
     );
@@ -37,13 +40,24 @@ describe("buildDevWebSocketUrl", () => {
     );
   });
 
+  it("uses the proxied app origin for HTTP local Cloud", () => {
+    vi.stubGlobal("__BB_DEV_WS_BROWSER_HOST_PORT__", 23_802);
+    vi.stubGlobal("__BB_DEV_APP_BROWSER_HOST_PORT__", 15_802);
+    installWindowLocation("http://sawyer.localhost:35802/threads/thr_1");
+
+    expect(buildDevWebSocketUrl({ path: "/ws" })).toBe(
+      "ws://sawyer.localhost:35802/ws",
+    );
+  });
+
   it("preserves terminal websocket paths on the proxied app origin", () => {
     vi.stubGlobal("__BB_DEV_WS_BROWSER_HOST_PORT__", 23_802);
+    vi.stubGlobal("__BB_DEV_APP_BROWSER_HOST_PORT__", 15_802);
     installWindowLocation("https://dev.example.test:15802/threads/thr_1");
 
-    expect(
-      buildDevWebSocketUrl({ path: "/ws/terminals/term_1" }),
-    ).toBe("wss://dev.example.test:15802/ws/terminals/term_1");
+    expect(buildDevWebSocketUrl({ path: "/ws/terminals/term_1" })).toBe(
+      "wss://dev.example.test:15802/ws/terminals/term_1",
+    );
   });
 
   it("returns undefined outside the dev build", () => {
diff --git a/apps/app/src/lib/dev-websocket-url.ts b/apps/app/src/lib/dev-websocket-url.ts
index 9101e33b9c..5ae6bae372 100644
--- a/apps/app/src/lib/dev-websocket-url.ts
+++ b/apps/app/src/lib/dev-websocket-url.ts
@@ -2,25 +2,35 @@ interface BuildDevWebSocketUrlArgs {
   path: string;
 }
 
-function resolveBrowserHostDevWebSocketBaseUrl(port: number): string {
+function resolveBrowserHostDevWebSocketBaseUrl(
+  serverPort: number,
+  appPort: number,
+): string {
   const protocol = window.location.protocol === "https:" ? "wss:" : "ws:";
 
   // HTTPS dev origins are typically reverse proxies or bb connect shares.
   // Their public origin does not expose the backend's local TCP port, so keep
   // the socket on the app origin and let Vite proxy /ws to the server.
-  if (window.location.protocol === "https:") {
+  if (
+    window.location.protocol === "https:" ||
+    window.location.port !== String(appPort)
+  ) {
     return `${protocol}//${window.location.host}/ws`;
   }
 
   // Direct sockets remain preferable for ordinary localhost/LAN source dev:
   // they survive backend restarts more reliably than Vite's WS proxy.
-  return `${protocol}//${window.location.hostname}:${port}/ws`;
+  return `${protocol}//${window.location.hostname}:${serverPort}/ws`;
 }
 
 function resolveDevWebSocketBaseUrl(): string | undefined {
-  if (typeof __BB_DEV_WS_BROWSER_HOST_PORT__ === "number") {
+  if (
+    typeof __BB_DEV_WS_BROWSER_HOST_PORT__ === "number" &&
+    typeof __BB_DEV_APP_BROWSER_HOST_PORT__ === "number"
+  ) {
     return resolveBrowserHostDevWebSocketBaseUrl(
       __BB_DEV_WS_BROWSER_HOST_PORT__,
+      __BB_DEV_APP_BROWSER_HOST_PORT__,
     );
   }
 
diff --git a/apps/app/src/vite-env.d.ts b/apps/app/src/vite-env.d.ts
index a0ffd0ac7e..f7153037bc 100644
--- a/apps/app/src/vite-env.d.ts
+++ b/apps/app/src/vite-env.d.ts
@@ -2,3 +2,4 @@
 
 /** Injected by vite.dev.config.ts to bypass Vite's WebSocket proxy. */
 declare const __BB_DEV_WS_BROWSER_HOST_PORT__: number | undefined;
+declare const __BB_DEV_APP_BROWSER_HOST_PORT__: number | undefined;
diff --git a/apps/app/vite.dev.config.ts b/apps/app/vite.dev.config.ts
index 1d89e9766e..c616dc5f9a 100644
--- a/apps/app/vite.dev.config.ts
+++ b/apps/app/vite.dev.config.ts
@@ -13,6 +13,7 @@ export default defineConfig({
     // Connect directly to the server in dev because Vite's WS proxy does not
     // handle upstream server restarts reliably.
     __BB_DEV_WS_BROWSER_HOST_PORT__: devWebSocketBrowserHostPortDefine,
+    __BB_DEV_APP_BROWSER_HOST_PORT__: JSON.stringify(viteDevConfig.appPort),
   },
   server: {
     // Allow Tailscale MagicDNS names when Vite is behind Tailscale Serve.
diff --git a/apps/connect/src/cloud-dev.test.ts b/apps/connect/src/cloud-dev.test.ts
new file mode 100644
index 0000000000..f478cee086
--- /dev/null
+++ b/apps/connect/src/cloud-dev.test.ts
@@ -0,0 +1,61 @@
+import { describe, expect, it } from "vitest";
+import {
+  CLOUD_DEV_HOST_HEADER,
+  publicConnectOrigin,
+  resolveConnectRequestHost,
+  resolveConnectRequestUrl,
+  resolveConnectRuntime,
+} from "./cloud-dev.js";
+
+describe("local Cloud request routing", () => {
+  it("accepts the launcher host and selects HTTP cookies only in local Cloud", () => {
+    const runtime = resolveConnectRuntime({
+      ACCOUNT_APP_URL: "http://bb.localhost:8787",
+      BASE_DOMAIN: "bb.localhost",
+      CLOUD_DEV: "true",
+    });
+    const headers = new Headers({
+      host: "localhost",
+      [CLOUD_DEV_HOST_HEADER]: "sawyer--3000",
+    });
+    expect(resolveConnectRequestHost(headers, runtime)).toBe(
+      "sawyer--3000.bb.localhost",
+    );
+    expect(runtime.sessionCookieName).toBe("better-auth.session_token");
+    expect(runtime.desktopSessionCookieName).toBe("bb-connect.desktop_session");
+    expect(publicConnectOrigin("sawyer--3000", runtime)).toBe(
+      "http://sawyer--3000.bb.localhost:8787",
+    );
+    expect(
+      resolveConnectRequestUrl(
+        "http://127.0.0.1:50743/threads/thr_1?view=full",
+        headers,
+        runtime,
+      ).toString(),
+    ).toBe("http://sawyer--3000.bb.localhost:8787/threads/thr_1?view=full");
+  });
+
+  it("ignores the launcher header in production", () => {
+    const runtime = resolveConnectRuntime({ BASE_DOMAIN: "getbb.app" });
+    const headers = new Headers({
+      host: "sawyer.getbb.app",
+      [CLOUD_DEV_HOST_HEADER]: "attacker",
+    });
+    expect(resolveConnectRequestHost(headers, runtime)).toBe(
+      "sawyer.getbb.app",
+    );
+    expect(runtime.sessionCookieName).toBe(
+      "__Secure-better-auth.session_token",
+    );
+  });
+
+  it("rejects deployed credential auth", () => {
+    expect(() =>
+      resolveConnectRuntime({
+        ACCOUNT_APP_URL: "https://getbb.app",
+        BASE_DOMAIN: "getbb.app",
+        CLOUD_DEV: "true",
+      }),
+    ).toThrow("only allowed for local Cloud development");
+  });
+});
diff --git a/apps/connect/src/cloud-dev.ts b/apps/connect/src/cloud-dev.ts
new file mode 100644
index 0000000000..324407cdc4
--- /dev/null
+++ b/apps/connect/src/cloud-dev.ts
@@ -0,0 +1,112 @@
+export const CLOUD_DEV_HOST_HEADER = "x-bb-cloud-dev-host";
+export const SECURE_SESSION_COOKIE = "__Secure-better-auth.session_token";
+export const LOCAL_SESSION_COOKIE = "better-auth.session_token";
+export const SECURE_DESKTOP_SESSION_COOKIE =
+  "__Secure-bb-connect.desktop_session";
+export const LOCAL_DESKTOP_SESSION_COOKIE = "bb-connect.desktop_session";
+
+export interface ConnectRuntime {
+  accountAppUrl: string;
+  baseDomain: string;
+  localCloud: boolean;
+  sessionCookieName: string;
+  desktopSessionCookieName: string;
+}
+
+function resolveCloudDevLabel(
+  headers: Headers,
+  runtime: ConnectRuntime,
+): string | null {
+  if (!runtime.localCloud) return null;
+  const label = headers.get(CLOUD_DEV_HOST_HEADER)?.trim().toLowerCase();
+  return label && !label.includes(".") && /^[a-z0-9-]+$/u.test(label)
+    ? label
+    : null;
+}
+
+/** Resolve the small, fail-closed set of overrides used by local Cloud. */
+export function resolveConnectRuntime(env: {
+  ACCOUNT_APP_URL?: string;
+  BASE_DOMAIN: string;
+  CLOUD_DEV?: string;
+}): ConnectRuntime {
+  const accountAppUrl = new URL(
+    env.ACCOUNT_APP_URL?.trim() || `https://${env.BASE_DOMAIN}`,
+  );
+  if (
+    (accountAppUrl.protocol !== "http:" &&
+      accountAppUrl.protocol !== "https:") ||
+    accountAppUrl.username !== "" ||
+    accountAppUrl.password !== "" ||
+    accountAppUrl.pathname !== "/" ||
+    accountAppUrl.search !== "" ||
+    accountAppUrl.hash !== ""
+  ) {
+    throw new Error("ACCOUNT_APP_URL must be an HTTP(S) origin");
+  }
+
+  const cloudDevValue = env.CLOUD_DEV?.trim();
+  if (cloudDevValue && cloudDevValue !== "true") {
+    throw new Error("CLOUD_DEV must be true when set");
+  }
+  const localCloud = cloudDevValue === "true";
+  if (localCloud) {
+    const isLocalAccount =
+      accountAppUrl.protocol === "http:" &&
+      accountAppUrl.hostname === env.BASE_DOMAIN &&
+      env.BASE_DOMAIN.endsWith(".localhost");
+    if (!isLocalAccount) {
+      throw new Error("CLOUD_DEV is only allowed for local Cloud development");
+    }
+  }
+
+  return {
+    accountAppUrl: accountAppUrl.origin,
+    baseDomain: env.BASE_DOMAIN,
+    localCloud,
+    sessionCookieName: localCloud
+      ? LOCAL_SESSION_COOKIE
+      : SECURE_SESSION_COOKIE,
+    desktopSessionCookieName: localCloud
+      ? LOCAL_DESKTOP_SESSION_COOKIE
+      : SECURE_DESKTOP_SESSION_COOKIE,
+  };
+}
+
+/** Wrangler replaces wildcard hosts locally; the launcher preserves the label. */
+export function resolveConnectRequestHost(
+  headers: Headers,
+  runtime: ConnectRuntime,
+): string {
+  const ordinaryHost = headers.get("host") ?? "";
+  const label = resolveCloudDevLabel(headers, runtime);
+  return label === null ? ordinaryHost : `${label}.${runtime.baseDomain}`;
+}
+
+export function publicConnectOrigin(
+  label: string,
+  runtime: Pick<ConnectRuntime, "accountAppUrl" | "baseDomain">,
+): string {
+  const url = new URL(runtime.accountAppUrl);
+  url.hostname = `${label}.${runtime.baseDomain}`;
+  return url.origin;
+}
+
+export function resolveConnectRequestUrl(
+  requestUrl: string,
+  headers: Headers,
+  runtime: ConnectRuntime,
+): URL {
+  const parsed = new URL(requestUrl);
+  const label = resolveCloudDevLabel(headers, runtime);
+  if (label === null) return parsed;
+  const publicUrl = new URL(publicConnectOrigin(label, runtime));
+  publicUrl.pathname = parsed.pathname;
+  publicUrl.search = parsed.search;
+  publicUrl.hash = parsed.hash;
+  return publicUrl;
+}
+
+export function stripCloudDevHeader(headers: Headers): void {
+  headers.delete(CLOUD_DEV_HOST_HEADER);
+}
diff --git a/apps/connect/src/machine-label.ts b/apps/connect/src/machine-label.ts
index 134c797a0a..da3c1a9bbb 100644
--- a/apps/connect/src/machine-label.ts
+++ b/apps/connect/src/machine-label.ts
@@ -8,10 +8,9 @@ import {
   type ConnectDb,
 } from "@bb/connect-db";
 import { verifyMachineCredentialDetails } from "./session.js";
+import { MACHINE_CREDENTIAL_HEADER } from "./protocol-headers.js";
 import type { Env } from "./tunnel-do.js";
 
-const MACHINE_CREDENTIAL_HEADER = "x-bb-connect-machine";
-
 function fallbackLabel(machineId: string): string {
   const idPrefix = machineId
     .replace(/[^a-z0-9]/giu, "")
diff --git a/apps/connect/src/protocol-headers.ts b/apps/connect/src/protocol-headers.ts
new file mode 100644
index 0000000000..83fb7559b8
--- /dev/null
+++ b/apps/connect/src/protocol-headers.ts
@@ -0,0 +1,4 @@
+export const TUNNEL_TARGET_HEADER = "x-bb-tunnel-target";
+export const MACHINE_CREDENTIAL_HEADER = "x-bb-connect-machine";
+export const GATE_AUTH_HEADER = "x-bb-gate-auth";
+export const GATE_MACHINE_ID_HEADER = "x-bb-gate-machine-id";
diff --git a/apps/connect/src/servers.test.ts b/apps/connect/src/servers.test.ts
index 8112046dcb..80e59ff594 100644
--- a/apps/connect/src/servers.test.ts
+++ b/apps/connect/src/servers.test.ts
@@ -20,6 +20,7 @@ import {
   createDesktopSessionCookie,
   listAccountServers,
   resolveAccountUserId,
+  revokeServerCredential,
   verifyDesktopSessionCookie,
   verifyServerCredential,
 } from "./servers.js";
@@ -28,6 +29,7 @@ import {
   assignMachineLabelForCredential,
   sanitizeMachineLabelBase,
 } from "./machine-label.js";
+import { SECURE_SESSION_COOKIE } from "./cloud-dev.js";
 import { verifyMachineCredential } from "./session.js";
 
 // Real in-memory SQLite (never mock the DB). Same harness as session.test.ts.
@@ -220,6 +222,50 @@ describe("verifyServerCredential / resolveAccountUserId", () => {
     expect(await verifyServerCredential("wrong", db)).toBeNull();
   });
 
+  it("revokes only the row authenticated by the presenting server", async () => {
+    seedUser("acct-a");
+    const plaintext = "bbcred_revoke_this_server";
+    seedServer({
+      id: "s1",
+      userId: "acct-a",
+      name: "default",
+      subdomain: "sawyer",
+      credentialHash: await sha256Hex(plaintext),
+    });
+    seedServer({
+      id: "s2",
+      userId: "acct-a",
+      name: "desktop",
+      subdomain: "sawyer-desktop",
+      credentialHash: await sha256Hex("bbcred_keep_this_server"),
+    });
+
+    // Prime the warm-isolate credential cache before revoking.
+    expect(await verifyServerCredential(plaintext, db)).toBe("acct-a");
+    await expect(revokeServerCredential(plaintext, db)).resolves.toEqual({
+      subdomain: "sawyer",
+    });
+
+    const rows = await db
+      .select({
+        id: server.id,
+        credentialHash: server.credentialHash,
+        revokedAt: server.revokedAt,
+      })
+      .from(server)
+      .all();
+    expect(rows.find((row) => row.id === "s1")).toMatchObject({
+      credentialHash: null,
+      revokedAt: expect.any(Date),
+    });
+    expect(rows.find((row) => row.id === "s2")).toMatchObject({
+      credentialHash: await sha256Hex("bbcred_keep_this_server"),
+      revokedAt: null,
+    });
+    await expect(verifyServerCredential(plaintext, db)).resolves.toBeNull();
+    await expect(revokeServerCredential(plaintext, db)).resolves.toBeNull();
+  });
+
   it("authenticates a machine credential and isolates cross-account rows", async () => {
     seedUser("acct-a");
     seedUser("acct-b");
@@ -254,7 +300,12 @@ describe("verifyServerCredential / resolveAccountUserId", () => {
     const req = new Request("https://sawyer.getbb.app/api/connect/servers", {
       headers: { "x-bb-connect-machine": machinePlain },
     });
-    const userId = await resolveAccountUserId(req, "secret", db);
+    const userId = await resolveAccountUserId(
+      req,
+      "secret",
+      db,
+      SECURE_SESSION_COOKIE,
+    );
     expect(userId).toBe("acct-a");
     const listed = await listAccountServers(db, userId!, now.getTime());
     expect(listed.map((s) => s.handle)).toEqual(["sawyer"]);
@@ -262,7 +313,9 @@ describe("verifyServerCredential / resolveAccountUserId", () => {
 
   it("returns null (unauthorized) when no credential or session is presented", async () => {
     const req = new Request("https://sawyer.getbb.app/api/connect/servers");
-    expect(await resolveAccountUserId(req, "secret", db)).toBeNull();
+    expect(
+      await resolveAccountUserId(req, "secret", db, SECURE_SESSION_COOKIE),
+    ).toBeNull();
   });
 
   it("accepts a valid owner session cookie", async () => {
@@ -303,7 +356,24 @@ describe("verifyServerCredential / resolveAccountUserId", () => {
         cookie: `__Secure-better-auth.session_token=${cookieValue}`,
       },
     });
-    expect(await resolveAccountUserId(req, secret, db)).toBe("acct-a");
+    expect(
+      await resolveAccountUserId(req, secret, db, SECURE_SESSION_COOKIE),
+    ).toBe("acct-a");
+
+    const localRequest = new Request(
+      "http://sawyer.bb.localhost:8787/api/connect/servers",
+      {
+        headers: { cookie: `better-auth.session_token=${cookieValue}` },
+      },
+    );
+    expect(
+      await resolveAccountUserId(
+        localRequest,
+        secret,
+        db,
+        "better-auth.session_token",
+      ),
+    ).toBe("acct-a");
   });
 });
 
diff --git a/apps/connect/src/servers.ts b/apps/connect/src/servers.ts
index 3294bac531..0e0b4c3b32 100644
--- a/apps/connect/src/servers.ts
+++ b/apps/connect/src/servers.ts
@@ -11,10 +11,10 @@ import {
   verifyMachineCredential,
   verifySessionCookie,
 } from "./session.js";
+import { resolveConnectRuntime } from "./cloud-dev.js";
+import { MACHINE_CREDENTIAL_HEADER } from "./protocol-headers.js";
 import type { Env } from "./tunnel-do.js";
 
-const SESSION_COOKIE = "__Secure-better-auth.session_token";
-export const DESKTOP_SESSION_COOKIE = "__Secure-bb-connect.desktop_session";
 export const DESKTOP_SESSION_TTL_MS = 60 * 60 * 1000;
 
 function bytesToBase64Url(bytes: Uint8Array): string {
@@ -152,6 +152,29 @@ export async function verifyServerCredential(
   return userId;
 }
 
+/** Revoke exactly the active server row authenticated by `credential`. */
+export async function revokeServerCredential(
+  credential: string,
+  db: ConnectDb,
+): Promise<{ subdomain: string } | null> {
+  const presented = credential.trim();
+  if (!presented) return null;
+
+  const revoked = await db
+    .update(server)
+    .set({ credentialHash: null, revokedAt: new Date() })
+    .where(
+      and(
+        eq(server.credentialHash, await sha256Hex(presented)),
+        isNull(server.revokedAt),
+      ),
+    )
+    .returning({ subdomain: server.subdomain })
+    .get();
+  serverCredentialCache.delete(presented);
+  return revoked ?? null;
+}
+
 /**
  * Resolve the authenticated account for account-scoped connect APIs.
  *
@@ -167,8 +190,9 @@ export async function resolveAccountUserId(
   request: Request,
   secret: string,
   db: ConnectDb,
+  sessionCookieName: string,
 ): Promise<string | null> {
-  const presented = request.headers.get("x-bb-connect-machine") ?? "";
+  const presented = request.headers.get(MACHINE_CREDENTIAL_HEADER) ?? "";
   if (presented) {
     const machineUserId = await verifyMachineCredential(presented, db);
     if (machineUserId) return machineUserId;
@@ -179,7 +203,7 @@ export async function resolveAccountUserId(
     if (serverUserId) return serverUserId;
   }
 
-  const cookie = parseCookie(request.headers.get("cookie"), SESSION_COOKIE);
+  const cookie = parseCookie(request.headers.get("cookie"), sessionCookieName);
   if (!cookie) return null;
   return verifySessionCookie(cookie, secret, db);
 }
@@ -249,10 +273,12 @@ export async function handleListAccountServers(
   }
 
   const db = drizzle(env.DB, { schema });
+  const runtime = resolveConnectRuntime(env);
   const userId = await resolveAccountUserId(
     request,
     env.BETTER_AUTH_SECRET,
     db,
+    runtime.sessionCookieName,
   );
   if (!userId) {
     return new Response(JSON.stringify({ error: "unauthorized" }), {
@@ -268,6 +294,40 @@ export async function handleListAccountServers(
   });
 }
 
+/** `POST /api/connect/disconnect` — revoke the presenting bb itself. */
+export async function handleDisconnectServer(
+  request: Request,
+  env: Env,
+): Promise<Response> {
+  if (request.method !== "POST") {
+    return new Response(JSON.stringify({ error: "method_not_allowed" }), {
+      status: 405,
+      headers: {
+        "content-type": "application/json; charset=utf-8",
+        allow: "POST",
+      },
+    });
+  }
+
+  const db = drizzle(env.DB, { schema });
+  const credential = request.headers.get(MACHINE_CREDENTIAL_HEADER) ?? "";
+  const revoked = await revokeServerCredential(credential, db);
+  if (!revoked) {
+    return new Response(JSON.stringify({ error: "unauthorized" }), {
+      status: 401,
+      headers: { "content-type": "application/json; charset=utf-8" },
+    });
+  }
+
+  try {
+    const stub = env.TUNNEL_DO.get(env.TUNNEL_DO.idFromName(revoked.subdomain));
+    await stub.fetch("https://tunnel/__control/close");
+  } catch {
+    // Best-effort: the credential is already revoked, so reconnect is blocked.
+  }
+  return Response.json({ ok: true });
+}
+
 /** Exchange a durable pairing credential for a short-lived browser session. */
 export async function handleCreateDesktopSession(
   request: Request,
@@ -283,10 +343,12 @@ export async function handleCreateDesktopSession(
     });
   }
   const db = drizzle(env.DB, { schema });
+  const runtime = resolveConnectRuntime(env);
   const userId = await resolveAccountUserId(
     request,
     env.BETTER_AUTH_SECRET,
     db,
+    runtime.sessionCookieName,
   );
   if (!userId) {
     return new Response(JSON.stringify({ error: "unauthorized" }), {
@@ -305,7 +367,7 @@ export async function handleCreateDesktopSession(
       cookie: {
         domain: `.${env.BASE_DOMAIN}`,
         expiresAt,
-        name: DESKTOP_SESSION_COOKIE,
+        name: runtime.desktopSessionCookieName,
         value,
       },
     }),
diff --git a/apps/connect/src/tunnel-do.ts b/apps/connect/src/tunnel-do.ts
index c65df2953f..7eca8777af 100644
--- a/apps/connect/src/tunnel-do.ts
+++ b/apps/connect/src/tunnel-do.ts
@@ -11,12 +11,15 @@ import {
   type HeaderPair,
 } from "@bb/tunnel-contract";
 import { relayedResponse } from "./response-encoding.js";
+import { TUNNEL_TARGET_HEADER } from "./protocol-headers.js";
 
 export interface Env {
   TUNNEL_DO: DurableObjectNamespace;
   DB: D1Database;
   BASE_DOMAIN: string;
   BETTER_AUTH_SECRET: string;
+  ACCOUNT_APP_URL?: string;
+  CLOUD_DEV?: string;
 }
 
 const TUNNEL_TAG = "tunnel";
@@ -26,9 +29,6 @@ const RESP_HEAD_TIMEOUT_MS = 30_000;
 // run JS), kept under the 90s offline window.
 const PRESENCE_INTERVAL_MS = 50_000;
 
-/** Gate → DO header carrying a share target; never forwarded to the origin. */
-const TUNNEL_TARGET_HEADER = "x-bb-tunnel-target";
-
 // Standard WebSocket readyState numbering (workerd's READY_STATE_OPEN; the
 // constant itself is Cloudflare-only, so tests in Node use the number).
 const WS_READY_STATE_OPEN = 1;
diff --git a/apps/connect/src/worker.test.ts b/apps/connect/src/worker.test.ts
index c69c7aa246..bf26c7c222 100644
--- a/apps/connect/src/worker.test.ts
+++ b/apps/connect/src/worker.test.ts
@@ -5,13 +5,15 @@ import { machine } from "@bb/connect-db";
 import { cacheKey } from "./cache";
 import { parseClientProtocolVersion } from "./tunnel-do";
 import {
-  GATE_AUTH_HEADER,
-  GATE_MACHINE_ID_HEADER,
-  TUNNEL_TARGET_HEADER,
   cacheNamespace,
   dashboardSignInUrl,
   requestForTunnelDo,
 } from "./worker";
+import {
+  GATE_AUTH_HEADER,
+  GATE_MACHINE_ID_HEADER,
+  TUNNEL_TARGET_HEADER,
+} from "./protocol-headers";
 
 // ── pure helpers ────────────────────────────────────────────────────────────
 
@@ -112,8 +114,8 @@ vi.mock("./session.js", () => ({
 }));
 
 vi.mock("./servers.js", () => ({
-  DESKTOP_SESSION_COOKIE: "__Secure-bb-connect.desktop_session",
   handleCreateDesktopSession: vi.fn(),
+  handleDisconnectServer: vi.fn(),
   handleListAccountServers: vi.fn(),
   verifyDesktopSessionCookie: vi.fn(),
 }));
@@ -152,11 +154,12 @@ import {
   verifySessionCookie,
 } from "./session.js";
 import {
-  DESKTOP_SESSION_COOKIE,
   handleCreateDesktopSession,
+  handleDisconnectServer,
   handleListAccountServers,
   verifyDesktopSessionCookie,
 } from "./servers.js";
+import { SECURE_DESKTOP_SESSION_COOKIE as DESKTOP_SESSION_COOKIE } from "./cloud-dev.js";
 import { handleAssignMachineLabel } from "./machine-label.js";
 import { serveWithCache } from "./cache.js";
 import worker, { offlinePage, relativeTime, wantsHtml } from "./worker.js";
@@ -170,6 +173,7 @@ const mockVerifySession = vi.mocked(verifySessionCookie);
 const mockServeWithCache = vi.mocked(serveWithCache);
 const mockHandleListAccountServers = vi.mocked(handleListAccountServers);
 const mockHandleCreateDesktopSession = vi.mocked(handleCreateDesktopSession);
+const mockHandleDisconnectServer = vi.mocked(handleDisconnectServer);
 const mockVerifyDesktopSession = vi.mocked(verifyDesktopSessionCookie);
 const mockHandleAssignMachineLabel = vi.mocked(handleAssignMachineLabel);
 
@@ -326,6 +330,27 @@ describe("POST /api/connect/desktop-session", () => {
   });
 });
 
+describe("POST /api/connect/disconnect", () => {
+  it("intercepts self-revocation before tunnel routing", async () => {
+    mockHandleDisconnectServer.mockResolvedValue(Response.json({ ok: true }));
+    const { env, ctx, captured } = makeEnv(() => new Response("origin"));
+    const request = visitorRequest(
+      "sawyer.getbb.app",
+      "/api/connect/disconnect",
+      {
+        method: "POST",
+        headers: { "x-bb-connect-machine": "paired" },
+      },
+    );
+    const response = await worker.fetch(request, env as never, ctx);
+
+    expect(response.status).toBe(200);
+    expect(mockHandleDisconnectServer).toHaveBeenCalledWith(request, env);
+    expect(mockResolveLabel).not.toHaveBeenCalled();
+    expect(captured).toHaveLength(0);
+  });
+});
+
 describe("POST /api/connect/machine-label", () => {
   it("intercepts machine-authenticated assignment before label routing", async () => {
     mockHandleAssignMachineLabel.mockResolvedValue(
@@ -377,7 +402,10 @@ describe("gate tunnel authentication", () => {
         "sawyer-air.getbb.app",
         "/__tunnel?v=1&serverId=victim-server&machineId=spoofed-machine",
         {
-          headers: { authorization: `Bearer ${credential}` },
+          headers: {
+            authorization: `Bearer ${credential}`,
+            "x-bb-cloud-dev-host": "smuggled",
+          },
         },
       ),
       env as never,
@@ -395,6 +423,7 @@ describe("gate tunnel authentication", () => {
       "machine-air",
     );
     expect(new URL(captured[0].url).searchParams.get("serverId")).toBeNull();
+    expect(captured[0].headers.get("x-bb-cloud-dev-host")).toBeNull();
   });
 
   it("dials immediately after a negative resolve and label assignment", async () => {
@@ -552,14 +581,20 @@ describe("machine gate auth", () => {
     const { env, ctx, captured } = makeEnv(() => new Response("origin"));
     const internal = await worker.fetch(
       visitorRequest("sawyer.getbb.app", "/internal/session/open", {
-        headers: { "x-bb-connect-machine": "bbcm_owner" },
+        headers: {
+          "x-bb-connect-machine": "bbcm_owner",
+          "x-bb-cloud-dev-host": "smuggled",
+        },
       }),
       env as never,
       ctx,
     );
     const api = await worker.fetch(
       visitorRequest("sawyer.getbb.app", "/api/v1/threads", {
-        headers: { "x-bb-connect-machine": "bbcm_owner" },
+        headers: {
+          "x-bb-connect-machine": "bbcm_owner",
+          "x-bb-cloud-dev-host": "smuggled",
+        },
       }),
       env as never,
       ctx,
@@ -572,6 +607,11 @@ describe("machine gate auth", () => {
         (request) => request.headers.get("x-bb-connect-machine") === null,
       ),
     ).toBe(true);
+    expect(
+      captured.every(
+        (request) => request.headers.get("x-bb-cloud-dev-host") === null,
+      ),
+    ).toBe(true);
     expect(
       captured.every(
         (request) => request.headers.get(GATE_AUTH_HEADER) === "machine",
@@ -630,13 +670,16 @@ describe("machine gate auth", () => {
     async (path) => {
       const { env, ctx, captured } = makeEnv(() => new Response("artifact"));
       const response = await worker.fetch(
-        visitorRequest("sawyer.getbb.app", path),
+        visitorRequest("sawyer.getbb.app", path, {
+          headers: { "x-bb-cloud-dev-host": "smuggled" },
+        }),
         env as never,
         ctx,
       );
       expect(response.status).toBe(200);
       expect(await response.text()).toBe("artifact");
       expect(captured).toHaveLength(1);
+      expect(captured[0].headers.get("x-bb-cloud-dev-host")).toBeNull();
       expect(mockVerifyMachine).not.toHaveBeenCalled();
     },
   );
@@ -693,6 +736,30 @@ describe("gate worker share hosts", () => {
     expect(mockVerifySession).not.toHaveBeenCalled();
   });
 
+  it("renders local machine links with HTTP and the shared gateway port", async () => {
+    mockResolveLabel.mockResolvedValue(resolvedMachine());
+    const { env, ctx } = makeEnv(() => new Response("origin"));
+    Object.assign(env, {
+      ACCOUNT_APP_URL: "http://bb.localhost:42745",
+      BASE_DOMAIN: "bb.localhost",
+      CLOUD_DEV: "true",
+    });
+    const response = await worker.fetch(
+      new Request("http://127.0.0.1:50743/", {
+        headers: {
+          host: "127.0.0.1:50743",
+          "x-bb-cloud-dev-host": "sawyer-air",
+        },
+      }),
+      env as never,
+      ctx,
+    );
+
+    const html = await response.text();
+    expect(html).toContain("sawyer-air--&lt;port&gt;.bb.localhost:42745");
+    expect(html).toContain('href="http://sawyer.bb.localhost:42745"');
+  });
+
   it("applies the same owner-session check to machine share hosts", async () => {
     mockResolveLabel.mockResolvedValue(resolvedMachine());
     const ownerEnv = makeEnv(() => new Response("machine-origin"));
@@ -777,13 +844,17 @@ describe("gate worker share hosts", () => {
     const { env, ctx, captured } = makeEnv(() => new Response("ok"));
     await worker.fetch(
       visitorRequest("sawyer.getbb.app", "/", {
-        headers: { [TUNNEL_TARGET_HEADER]: "9999" },
+        headers: {
+          [TUNNEL_TARGET_HEADER]: "9999",
+          "x-bb-cloud-dev-host": "smuggled",
+        },
       }),
       env as never,
       ctx,
     );
     expect(captured).toHaveLength(1);
     expect(captured[0].headers.get(TUNNEL_TARGET_HEADER)).toBeNull();
+    expect(captured[0].headers.get("x-bb-cloud-dev-host")).toBeNull();
     expect(mockServeWithCache).toHaveBeenCalledWith(
       expect.any(Request),
       "sawyer",
@@ -848,6 +919,31 @@ describe("gate worker share hosts", () => {
     expect(captured).toHaveLength(0);
   });
 
+  it("preserves the public local URL in the sign-in returnTo", async () => {
+    mockParseCookie.mockReturnValue(null);
+    const { env, ctx } = makeEnv(() => new Response("ok"));
+    Object.assign(env, {
+      ACCOUNT_APP_URL: "http://bb.localhost:42745",
+      BASE_DOMAIN: "bb.localhost",
+      CLOUD_DEV: "true",
+    });
+    const response = await worker.fetch(
+      new Request("http://127.0.0.1:50743/threads/thr_1?view=full", {
+        headers: {
+          host: "127.0.0.1:50743",
+          "x-bb-cloud-dev-host": "sawyer",
+        },
+      }),
+      env as never,
+      ctx,
+    );
+
+    expect(response.status).toBe(401);
+    expect(await response.text()).toContain(
+      "returnTo=http%3A%2F%2Fsawyer.bb.localhost%3A42745%2Fthreads%2Fthr_1%3Fview%3Dfull",
+    );
+  });
+
   it("returns 403 when share host session is a different user", async () => {
     mockVerifySession.mockResolvedValue(OTHER);
     const { env, ctx, captured } = makeEnv(() => new Response("ok"));
diff --git a/apps/connect/src/worker.ts b/apps/connect/src/worker.ts
index 5776891e5a..9935622663 100644
--- a/apps/connect/src/worker.ts
+++ b/apps/connect/src/worker.ts
@@ -9,25 +9,30 @@ import {
   verifySessionCookie,
 } from "./session.js";
 import {
-  DESKTOP_SESSION_COOKIE,
   handleCreateDesktopSession,
+  handleDisconnectServer,
   handleListAccountServers,
   verifyDesktopSessionCookie,
 } from "./servers.js";
 import { serveWithCache } from "./cache.js";
 import { BB_ICON_DATA_URI } from "./bb-icon.js";
 import { handleAssignMachineLabel } from "./machine-label.js";
+import {
+  publicConnectOrigin,
+  resolveConnectRequestHost,
+  resolveConnectRequestUrl,
+  resolveConnectRuntime,
+  stripCloudDevHeader,
+} from "./cloud-dev.js";
+import {
+  GATE_AUTH_HEADER,
+  GATE_MACHINE_ID_HEADER,
+  MACHINE_CREDENTIAL_HEADER,
+  TUNNEL_TARGET_HEADER,
+} from "./protocol-headers.js";
 
 export { TunnelDO };
 
-const SESSION_COOKIE = "__Secure-better-auth.session_token";
-
-/** Internal header: gate → TunnelDO, share target (port string). Never trust visitors. */
-export const TUNNEL_TARGET_HEADER = "x-bb-tunnel-target";
-export const MACHINE_CREDENTIAL_HEADER = "x-bb-connect-machine";
-export const GATE_AUTH_HEADER = "x-bb-gate-auth";
-export const GATE_MACHINE_ID_HEADER = "x-bb-gate-machine-id";
-
 async function sha256Hex(value: string): Promise<string> {
   const digest = await crypto.subtle.digest(
     "SHA-256",
@@ -198,13 +203,15 @@ export function offlinePage(
 export function machinePage(
   label: string,
   accountHandle: string,
-  baseDomain: string,
+  runtime: ReturnType<typeof resolveConnectRuntime>,
 ): Response {
-  const appHost = `${accountHandle}.${baseDomain}`;
+  const appOrigin = publicConnectOrigin(accountHandle, runtime);
+  const appHost = new URL(appOrigin).host;
+  const baseHost = new URL(runtime.accountAppUrl).host;
   return gatePage(
     `<h1><code>${escapeHtml(label)}</code> is a machine</h1>
-     <p>This machine is on <code>${escapeHtml(accountHandle)}</code>'s account. Its shares appear at <code>${escapeHtml(label)}--&lt;port&gt;.${escapeHtml(baseDomain)}</code>.</p>
-     <a class="btn primary" href="https://${escapeHtml(appHost)}">Open the bb app at ${escapeHtml(appHost)}</a>`,
+     <p>This machine is on <code>${escapeHtml(accountHandle)}</code>'s account. Its shares appear at <code>${escapeHtml(label)}--&lt;port&gt;.${escapeHtml(baseHost)}</code>.</p>
+     <a class="btn primary" href="${escapeHtml(appOrigin)}">Open the bb app at ${escapeHtml(appHost)}</a>`,
     200,
   );
 }
@@ -223,6 +230,7 @@ export function requestForTunnelDo(
   headers.delete(MACHINE_CREDENTIAL_HEADER);
   headers.delete(GATE_AUTH_HEADER);
   headers.delete(GATE_MACHINE_ID_HEADER);
+  stripCloudDevHeader(headers);
   if (target !== null) {
     headers.set(TUNNEL_TARGET_HEADER, target);
   }
@@ -265,13 +273,17 @@ export default {
     env: Env,
     ctx: ExecutionContext,
   ): Promise<Response> {
-    const url = new URL(request.url);
+    const runtime = resolveConnectRuntime(env);
+    const url = resolveConnectRequestUrl(request.url, request.headers, runtime);
     // Account-scoped APIs are handled on the gate before host/label routing so
     // they never proxy through a tunnel to a local bb origin. Auth is
     // machine/server credential or owner session — see servers.ts.
     if (url.pathname === "/api/connect/servers") {
       return handleListAccountServers(request, env);
     }
+    if (url.pathname === "/api/connect/disconnect") {
+      return handleDisconnectServer(request, env);
+    }
     if (url.pathname === "/api/connect/desktop-session") {
       return handleCreateDesktopSession(request, env);
     }
@@ -279,7 +291,7 @@ export default {
       return handleAssignMachineLabel(request, env);
     }
 
-    const host = request.headers.get("host") ?? url.host;
+    const host = resolveConnectRequestHost(request.headers, runtime);
     const parsed = parseVisitorHost(host, env.BASE_DOMAIN);
     if (!parsed) return text("bb connect: unknown host\n", 404);
     // The base label is now ANY server's subdomain (the account handle names the
@@ -291,7 +303,7 @@ export default {
     // rather than answering with a confusing "no server" page.
     if (RESERVED_HANDLES.has(label)) {
       return Response.redirect(
-        `https://${env.BASE_DOMAIN}${url.pathname}${url.search}`,
+        `${runtime.accountAppUrl}${url.pathname}${url.search}`,
         301,
       );
     }
@@ -342,7 +354,11 @@ export default {
       } else {
         forward.searchParams.set("machineId", owner.id);
       }
-      return stub.fetch(new Request(forward, request));
+      const headers = new Headers(request.headers);
+      stripCloudDevHeader(headers);
+      return stub.fetch(
+        new Request(new Request(forward, request), { headers }),
+      );
     }
 
     // Reserve the /__ namespace: never proxy internal paths from outside.
@@ -352,7 +368,7 @@ export default {
     // Machine labels route only explicit `<label>--<port>` shares. The bare
     // label is an informational gate page and never reaches the machine DO.
     if (resolved.kind === "machine" && target === null) {
-      return machinePage(label, resolved.accountHandle, env.BASE_DOMAIN);
+      return machinePage(label, resolved.accountHandle, runtime);
     }
 
     // The bootstrap script and its server-matched package must be reachable
@@ -368,6 +384,7 @@ export default {
       headers.delete(TUNNEL_TARGET_HEADER);
       headers.delete(GATE_AUTH_HEADER);
       headers.delete(GATE_MACHINE_ID_HEADER);
+      stripCloudDevHeader(headers);
       return stub.fetch(new Request(request, { headers }));
     }
 
@@ -401,6 +418,7 @@ export default {
       headers.delete(TUNNEL_TARGET_HEADER);
       headers.delete(GATE_AUTH_HEADER);
       headers.delete(GATE_MACHINE_ID_HEADER);
+      stripCloudDevHeader(headers);
       headers.set(GATE_AUTH_HEADER, "machine");
       headers.set(GATE_MACHINE_ID_HEADER, verified.machineId);
       return stub.fetch(new Request(request, { headers }));
@@ -413,9 +431,12 @@ export default {
     // Identical auth for bare-label and share hosts. Because this check passed,
     // only the owner ever reaches the DO below (and thus its offline 503).
     const cookieHeader = request.headers.get("cookie");
-    const cookie = parseCookie(cookieHeader, SESSION_COOKIE);
-    const desktopCookie = parseCookie(cookieHeader, DESKTOP_SESSION_COOKIE);
-    const appUrl = `https://${env.BASE_DOMAIN}`;
+    const cookie = parseCookie(cookieHeader, runtime.sessionCookieName);
+    const desktopCookie = parseCookie(
+      cookieHeader,
+      runtime.desktopSessionCookieName,
+    );
+    const appUrl = runtime.accountAppUrl;
     if (!cookie && !desktopCookie)
       return signInPage(label, appUrl, url.toString());
     const sessionUserId = cookie
diff --git a/apps/host-daemon/package.json b/apps/host-daemon/package.json
index af9a0b2266..58d1c09745 100644
--- a/apps/host-daemon/package.json
+++ b/apps/host-daemon/package.json
@@ -24,6 +24,7 @@
   "dependencies": {
     "@bb/agent-runtime": "workspace:*",
     "@bb/cli": "workspace:*",
+    "@bb/connect-client": "workspace:*",
     "@bb/config": "workspace:*",
     "@bb/domain": "workspace:*",
     "@bb/fuzzy-match": "workspace:*",
diff --git a/apps/host-daemon/src/connect-tunnel/connect-tunnel.test.ts b/apps/host-daemon/src/connect-tunnel/connect-tunnel.test.ts
index 35db6bd6e1..61b0982bd3 100644
--- a/apps/host-daemon/src/connect-tunnel/connect-tunnel.test.ts
+++ b/apps/host-daemon/src/connect-tunnel/connect-tunnel.test.ts
@@ -11,7 +11,10 @@ import { WebSocket, WebSocketServer, type RawData } from "ws";
 import type { HostDaemonConnectTunnelIdentity } from "@bb/host-daemon-contract";
 import type { HostDaemonLogger } from "../logger.js";
 import {
+  buildMachineSharePublicOrigin,
+  buildMachineTunnelUrl,
   ConnectTunnelClient,
+  resolveTrustedConnectGate,
   type ConnectTunnelFetch,
   type ConnectTunnelStatus,
   type CreateTunnelWebSocket,
@@ -117,6 +120,33 @@ afterEach(async () => {
 });
 
 describe("ConnectTunnelClient", () => {
+  it("allows HTTP only for a local machine gate and derives ws URLs", () => {
+    expect(
+      resolveTrustedConnectGate("http://owner.bb.localhost:42745"),
+    ).toEqual({
+      apiOrigin: "http://owner.bb.localhost:42745",
+      baseDomain: "bb.localhost:42745",
+    });
+    expect(
+      buildMachineTunnelUrl({
+        label: "sawyer-air",
+        baseDomain: "bb.localhost:42745",
+      }),
+    ).toBe("ws://sawyer-air.bb.localhost:42745/__tunnel?v=1");
+    expect(
+      buildMachineSharePublicOrigin(
+        { label: "sawyer-air", baseDomain: "bb.localhost:42745" },
+        4173,
+      ),
+    ).toBe("http://sawyer-air--4173.bb.localhost:42745");
+    expect(() => resolveTrustedConnectGate("http://owner.getbb.app")).toThrow(
+      "require HTTPS",
+    );
+    expect(() =>
+      resolveTrustedConnectGate("https://owner.bb.localhost:42745"),
+    ).toThrow("HTTP for a local *.localhost");
+  });
+
   it("assigns its own label at the enrolled gate, dials on first share, and closes on the last", async () => {
     const gateServer = createServer();
     const gatePort = await listen(gateServer);
diff --git a/apps/host-daemon/src/connect-tunnel/index.ts b/apps/host-daemon/src/connect-tunnel/index.ts
index 2b82b9b4b4..0bcedf7739 100644
--- a/apps/host-daemon/src/connect-tunnel/index.ts
+++ b/apps/host-daemon/src/connect-tunnel/index.ts
@@ -15,6 +15,7 @@ import {
   type HostDaemonConnectShares,
   type HostDaemonConnectTunnelIdentity,
 } from "@bb/host-daemon-contract";
+import { connectPublicProtocol } from "@bb/connect-client";
 import type { HostDaemonLogger } from "../logger.js";
 
 export type ConnectTunnelState = "connected" | "reconnecting" | "offline";
@@ -67,11 +68,6 @@ export function resolveTrustedConnectGate(
   serverUrl: string,
 ): TrustedConnectGate {
   const parsed = new URL(serverUrl);
-  if (parsed.protocol !== "https:") {
-    throw new Error(
-      `bb connect machine credentials require an HTTPS enrollment server, got ${parsed.origin}`,
-    );
-  }
   const firstDot = parsed.hostname.indexOf(".");
   if (firstDot <= 0 || firstDot === parsed.hostname.length - 1) {
     throw new Error(
@@ -79,22 +75,37 @@ export function resolveTrustedConnectGate(
     );
   }
   const baseHostname = parsed.hostname.slice(firstDot + 1);
+  const baseDomain = `${baseHostname}${parsed.port ? `:${parsed.port}` : ""}`;
+  if (parsed.protocol !== connectPublicProtocol(baseDomain)) {
+    throw new Error(
+      `bb connect machine credentials require HTTPS, or HTTP for a local *.localhost enrollment server, got ${parsed.origin}`,
+    );
+  }
   return {
     apiOrigin: parsed.origin,
-    baseDomain: `${baseHostname}${parsed.port ? `:${parsed.port}` : ""}`,
+    baseDomain,
   };
 }
 
 export function buildMachineTunnelUrl(
   identity: HostDaemonConnectTunnelIdentity,
 ): string {
+  const websocketProtocol =
+    connectPublicProtocol(identity.baseDomain) === "https:" ? "wss:" : "ws:";
   const url = new URL(
-    `wss://${identity.label}.${identity.baseDomain}/__tunnel`,
+    `${websocketProtocol}//${identity.label}.${identity.baseDomain}/__tunnel`,
   );
   url.searchParams.set(TUNNEL_PROTOCOL_QUERY_PARAM, String(PROTOCOL_VERSION));
   return url.toString();
 }
 
+export function buildMachineSharePublicOrigin(
+  identity: HostDaemonConnectTunnelIdentity,
+  port: number,
+): string {
+  return `${connectPublicProtocol(identity.baseDomain)}//${identity.label}--${port}.${identity.baseDomain}`;
+}
+
 /**
  * Host-local connect primitive. The server supplies only desired ports. This
  * daemon derives the credential-bearing gate destination from its own trusted
@@ -450,7 +461,7 @@ export class ConnectTunnelClient {
       kind: "ok",
       resolved: {
         origin: `http://127.0.0.1:${port}`,
-        publicOrigin: `https://${identity.label}--${port}.${identity.baseDomain}`,
+        publicOrigin: buildMachineSharePublicOrigin(identity, port),
         host: `127.0.0.1:${port}`,
       },
     };
diff --git a/apps/server/src/services/skills/builtin-skills/bb-cli/SKILL.md b/apps/server/src/services/skills/builtin-skills/bb-cli/SKILL.md
index cdc754a913..93a043b1e5 100644
--- a/apps/server/src/services/skills/builtin-skills/bb-cli/SKILL.md
+++ b/apps/server/src/services/skills/builtin-skills/bb-cli/SKILL.md
@@ -180,6 +180,10 @@ isolated|reuse`, or anchor with `--source-seq-end`. Permission mode inherits
   https://getbb.app). Pairing returns immediately — the
   server itself holds the tunnel and reconnects on restart, so there is no
   foreground process.
+  In a source checkout, `pnpm dev` automatically sets
+  `BB_DEV_CONNECT_BASE_URL` to the worktree's local Cloud origin. Connect uses
+  it only as the unpaired default; explicit `--server` and `--base-url` values
+  still win, including when pairing the dev bb with getbb.app.
   `bb connect status` / `bb connect off` report and clear the pairing.
   Port sharing works from a thread on any enrolled host. `bb connect expose
 <port>` resolves that thread's environment host and returns its public URL;
diff --git a/apps/web/src/lib/connect-return-to.test.ts b/apps/web/src/lib/connect-return-to.test.ts
index c8a8cef59a..a44ced11af 100644
--- a/apps/web/src/lib/connect-return-to.test.ts
+++ b/apps/web/src/lib/connect-return-to.test.ts
@@ -21,6 +21,15 @@ describe("connect return-to URLs", () => {
     ).toBe("https://sawyer.vibecodethis.site/");
   });
 
+  it("accepts local Cloud handles under the shared cookie domain", () => {
+    expect(
+      connectReturnTo(
+        "http://sawyer.bb.localhost:42745/threads/thr_1",
+        "http://bb.localhost:42745",
+      ),
+    ).toBe("http://sawyer.bb.localhost:42745/threads/thr_1");
+  });
+
   it("rejects nested subdomains and off-domain return targets", () => {
     expect(
       connectReturnTo("https://a.b.getbb.app/", "https://getbb.app"),
diff --git a/apps/web/src/lib/dashboard-live-state.test.ts b/apps/web/src/lib/dashboard-live-state.test.ts
new file mode 100644
index 0000000000..a326ae806b
--- /dev/null
+++ b/apps/web/src/lib/dashboard-live-state.test.ts
@@ -0,0 +1,31 @@
+import { describe, expect, it } from "vitest";
+import {
+  dashboardRefreshIntervalMs,
+  visibleServerPanel,
+} from "./dashboard-live-state.js";
+
+describe("dashboard live state", () => {
+  it("hides a stale setup panel as soon as pairing completes", () => {
+    expect(visibleServerPanel(true, "setup")).toBe("none");
+    expect(visibleServerPanel(false, "setup")).toBe("setup");
+    expect(visibleServerPanel(true, "repair")).toBe("repair");
+  });
+
+  it("keeps refreshing paired servers after the fast pairing phase", () => {
+    expect(
+      dashboardRefreshIntervalMs(
+        [{ connected: false, lastSeenAt: null }],
+        null,
+      ),
+    ).toBe(3_000);
+    expect(
+      dashboardRefreshIntervalMs([{ connected: true, lastSeenAt: null }], null),
+    ).toBe(3_000);
+    expect(
+      dashboardRefreshIntervalMs(
+        [{ connected: true, lastSeenAt: Date.now() }],
+        null,
+      ),
+    ).toBe(10_000);
+  });
+});
diff --git a/apps/web/src/lib/dashboard-live-state.ts b/apps/web/src/lib/dashboard-live-state.ts
new file mode 100644
index 0000000000..345d6a3969
--- /dev/null
+++ b/apps/web/src/lib/dashboard-live-state.ts
@@ -0,0 +1,20 @@
+export type ServerPanel = "none" | "setup" | "repair";
+
+/** A completed pairing always wins over stale local setup-panel state. */
+export function visibleServerPanel(
+  connected: boolean,
+  requestedPanel: ServerPanel,
+): ServerPanel {
+  return connected && requestedPanel === "setup" ? "none" : requestedPanel;
+}
+
+/** Poll quickly during pairing, but never stop observing a paired server. */
+export function dashboardRefreshIntervalMs(
+  servers: ReadonlyArray<{ connected: boolean; lastSeenAt: number | null }>,
+  pendingServerId: string | null,
+): number {
+  const pairing =
+    pendingServerId !== null ||
+    servers.some((server) => !server.connected || server.lastSeenAt === null);
+  return pairing ? 3_000 : 10_000;
+}
diff --git a/apps/web/src/routes/dashboard.tsx b/apps/web/src/routes/dashboard.tsx
index ce966c5347..ad55dda7db 100644
--- a/apps/web/src/routes/dashboard.tsx
+++ b/apps/web/src/routes/dashboard.tsx
@@ -1,4 +1,4 @@
-import { useCallback, useEffect, useState } from "react";
+import { useCallback, useEffect, useState, type FormEvent } from "react";
 import { createFileRoute, useRouter } from "@tanstack/react-router";
 import { HugeiconsIcon } from "@hugeicons/react";
 import {
@@ -11,6 +11,8 @@ import { MAX_SERVERS_PER_ACCOUNT } from "@bb/connect-db";
 import type { HandleValidationError, LabelAvailability } from "@bb/connect-db";
 import appCss from "../styles.css?url";
 import { Button } from "@/components/ui/button";
+import { Input } from "@/components/ui/input";
+import { Label } from "@/components/ui/label";
 import { cn } from "@/lib/utils";
 import {
   checkAvailabilityFn,
@@ -25,6 +27,11 @@ import {
 import type { IssuedCode, MachineSummary, ServerSummary } from "@/server/api";
 import bbIcon from "../assets/bb-icon.png";
 import { DASHBOARD_PATH, connectReturnTo } from "@/lib/connect-return-to";
+import {
+  dashboardRefreshIntervalMs,
+  visibleServerPanel,
+  type ServerPanel,
+} from "@/lib/dashboard-live-state";
 
 interface DashboardSearch {
   returnTo?: string;
@@ -304,6 +311,34 @@ async function signInWithGithub(returnTo: string | undefined) {
   if (data.url) window.location.href = data.url;
 }
 
+type EmailAuthMode = "sign-in" | "sign-up";
+
+function authResponseMessage(value: unknown): string | null {
+  if (typeof value !== "object" || value === null) return null;
+  if (!("message" in value) || typeof value.message !== "string") return null;
+  return value.message;
+}
+
+async function authenticateWithEmail(input: {
+  email: string;
+  mode: EmailAuthMode;
+  name: string;
+  password: string;
+}): Promise<string | null> {
+  const body =
+    input.mode === "sign-up"
+      ? { email: input.email, name: input.name, password: input.password }
+      : { email: input.email, password: input.password };
+  const response = await fetch(`/api/auth/${input.mode}/email`, {
+    method: "POST",
+    headers: { "content-type": "application/json" },
+    body: JSON.stringify(body),
+  });
+  const responseBody: unknown = await response.json().catch(() => null);
+  if (response.ok) return null;
+  return authResponseMessage(responseBody) ?? "Could not authenticate";
+}
+
 async function signOut() {
   // better-auth requires the JSON content-type (else 415) and a JSON body
   // (an empty body makes it 500); the browser supplies the Origin it checks.
@@ -327,14 +362,63 @@ function Home() {
     if (returnTo) window.location.assign(returnTo);
   }, [data.authed, search.returnTo]);
 
-  if (!data.authed) return <SignInView returnTo={search.returnTo} />;
-  if (!data.handle) return <ClaimView baseDomain={data.baseDomain} />;
+  if (!data.authed)
+    return (
+      <SignInView
+        emailPasswordEnabled={data.emailPasswordEnabled}
+        returnTo={search.returnTo}
+      />
+    );
+  if (!data.handle)
+    return <ClaimView serverUrlTemplate={data.serverUrlTemplate} />;
   return <AccountDashboard state={data} />;
 }
 
 /* ── W1: sign in ──────────────────────────────────────────────────── */
 
-function SignInView({ returnTo }: { returnTo: string | undefined }) {
+function SignInView({
+  emailPasswordEnabled,
+  returnTo,
+}: {
+  emailPasswordEnabled: boolean;
+  returnTo: string | undefined;
+}) {
+  const [mode, setMode] = useState<EmailAuthMode>("sign-in");
+  const [name, setName] = useState("");
+  const [email, setEmail] = useState("");
+  const [password, setPassword] = useState("");
+  const [error, setError] = useState<string | null>(null);
+  const [submitting, setSubmitting] = useState(false);
+
+  const submitEmail = async (event: FormEvent<HTMLFormElement>) => {
+    event.preventDefault();
+    const trimmedName = name.trim();
+    if (mode === "sign-up" && !trimmedName) {
+      setError("Enter your name");
+      return;
+    }
+    setSubmitting(true);
+    setError(null);
+    try {
+      const authError = await authenticateWithEmail({
+        email: email.trim(),
+        mode,
+        name: trimmedName,
+        password,
+      });
+      if (authError) {
+        setError(authError);
+        return;
+      }
+      window.location.href =
+        connectReturnTo(returnTo, window.location.origin) ?? DASHBOARD_PATH;
+    } catch {
+      setError("Could not reach the authentication service");
+    } finally {
+      setSubmitting(false);
+    }
+  };
+
   return (
     <Shell>
       <WebCard>
@@ -343,8 +427,95 @@ function SignInView({ returnTo }: { returnTo: string | undefined }) {
           Give your bb a private URL and open it from any browser. Your code and
           data never leave your machine.
         </p>
+        {emailPasswordEnabled ? (
+          <>
+            <form
+              className="space-y-3"
+              onSubmit={(event) => void submitEmail(event)}
+            >
+              {mode === "sign-up" ? (
+                <div className="space-y-1.5">
+                  <Label htmlFor="auth-name">Name</Label>
+                  <Input
+                    id="auth-name"
+                    autoComplete="name"
+                    value={name}
+                    onChange={(event) => setName(event.target.value)}
+                    disabled={submitting}
+                    required
+                  />
+                </div>
+              ) : null}
+              <div className="space-y-1.5">
+                <Label htmlFor="auth-email">Email</Label>
+                <Input
+                  id="auth-email"
+                  type="email"
+                  autoComplete="email"
+                  value={email}
+                  onChange={(event) => setEmail(event.target.value)}
+                  disabled={submitting}
+                  required
+                />
+              </div>
+              <div className="space-y-1.5">
+                <Label htmlFor="auth-password">Password</Label>
+                <Input
+                  id="auth-password"
+                  type="password"
+                  autoComplete={
+                    mode === "sign-up" ? "new-password" : "current-password"
+                  }
+                  value={password}
+                  onChange={(event) => setPassword(event.target.value)}
+                  disabled={submitting}
+                  minLength={8}
+                  required
+                />
+              </div>
+              {error ? (
+                <p className="text-sm text-destructive" role="alert">
+                  {error}
+                </p>
+              ) : null}
+              <Button
+                className="w-full justify-center py-[11px]"
+                type="submit"
+                disabled={submitting}
+              >
+                {submitting
+                  ? "Working…"
+                  : mode === "sign-up"
+                    ? "Create local account"
+                    : "Sign in with email"}
+              </Button>
+            </form>
+            <p className="mt-3 text-center text-xs text-muted-foreground">
+              {mode === "sign-in"
+                ? "New to this local Cloud?"
+                : "Already registered?"}{" "}
+              <button
+                className="font-medium text-foreground underline-offset-2 hover:underline"
+                type="button"
+                disabled={submitting}
+                onClick={() => {
+                  setError(null);
+                  setMode(mode === "sign-in" ? "sign-up" : "sign-in");
+                }}
+              >
+                {mode === "sign-in" ? "Create an account" : "Sign in"}
+              </button>
+            </p>
+            <div className="my-4 flex items-center gap-3 text-xs text-subtle-foreground">
+              <span className="h-px flex-1 bg-border" />
+              or
+              <span className="h-px flex-1 bg-border" />
+            </div>
+          </>
+        ) : null}
         <Button
           className="w-full justify-center py-[11px]"
+          type="button"
           onClick={() => void signInWithGithub(returnTo)}
         >
           <GithubMark />
@@ -361,7 +532,7 @@ function SignInView({ returnTo }: { returnTo: string | undefined }) {
 /* ── shared claim field (W2 handle + M2 label) ────────────────────── */
 
 function ClaimField({
-  baseDomain,
+  serverUrlTemplate,
   initial = "",
   autoFocus,
   previewLead = "Your bb will live at",
@@ -371,7 +542,7 @@ function ClaimField({
   cancelLabel = "Cancel",
   layout,
 }: {
-  baseDomain: string;
+  serverUrlTemplate: string;
   initial?: string;
   autoFocus?: boolean;
   previewLead?: string;
@@ -409,7 +580,8 @@ function ClaimField({
 
   const error = submitError ?? (avail ? availabilityCopy(avail) : null);
   const canSubmit = !busy && !!label && (avail?.available ?? false);
-  const preview = `https://${label || "you"}.${baseDomain}`;
+  const preview = serverUrlTemplate.replace("{label}", label || "you");
+  const addressSuffix = serverUrlTemplate.split("{label}")[1] ?? "";
 
   async function submit() {
     if (!canSubmit) return;
@@ -448,7 +620,7 @@ function ClaimField({
           aria-label="Address"
         />
         <span className="pr-3 font-mono text-sm text-subtle-foreground">
-          .{baseDomain}
+          {addressSuffix}
         </span>
       </div>
       <p className="mt-2.5 text-xs text-muted-foreground">
@@ -474,7 +646,7 @@ function ClaimField({
 
 /* ── W2: claim handle ─────────────────────────────────────────────── */
 
-function ClaimView({ baseDomain }: { baseDomain: string }) {
+function ClaimView({ serverUrlTemplate }: { serverUrlTemplate: string }) {
   const router = useRouter();
   return (
     <Shell>
@@ -488,9 +660,11 @@ function ClaimView({ baseDomain }: { baseDomain: string }) {
         </p>
         <ClaimField
           layout="card"
-          baseDomain={baseDomain}
+          serverUrlTemplate={serverUrlTemplate}
           buildSubmitLabel={(l) =>
-            l ? `Claim ${l}.${baseDomain}` : "Claim your address"
+            l
+              ? `Claim ${serverUrlTemplate.replace("{label}", l).replace(/^https?:\/\//u, "")}`
+              : "Claim your address"
           }
           onClaim={async (label) => {
             const r = await claimHandleFn({ data: label });
@@ -726,20 +900,19 @@ function RowMenu({
 
 function ServerRow({
   server,
-  baseDomain,
   autoPair,
 }: {
   server: ServerSummary;
-  baseDomain: string;
   /** First-run: the sole never-paired bb opens its pair panel by default. */
   autoPair?: boolean;
 }) {
   // A connected row toggles the re-pair panel; a never-paired row toggles its
   // setup panel. `panel` tracks which (if any) is showing under this row.
-  const [panel, setPanel] = useState<"none" | "setup" | "repair">(
+  const [panel, setPanel] = useState<ServerPanel>(
     autoPair && !server.connected ? "setup" : "none",
   );
   const [confirm, setConfirm] = useState<"disconnect" | "remove" | null>(null);
+  const visiblePanel = visibleServerPanel(server.connected, panel);
 
   const url = server.serverUrl;
   const copyUrl = () => void navigator.clipboard.writeText(url).catch(() => {});
@@ -780,10 +953,7 @@ function ServerRow({
       </span>
       <span className="min-w-0">
         <span className="block truncate font-mono text-sm font-medium leading-tight">
-          {server.subdomain}
-          <span className="font-normal text-subtle-foreground">
-            .{baseDomain}
-          </span>
+          {server.serverUrl.replace(/^https?:\/\//u, "")}
         </span>
         <span className="mt-px block text-xs text-muted-foreground">
           {server.online ? (
@@ -799,7 +969,7 @@ function ServerRow({
             <>
               Not set up ·{" "}
               <span className="text-foreground underline underline-offset-2">
-                {panel === "setup" ? "hide code" : "get connect code"}
+                {visiblePanel === "setup" ? "hide code" : "get connect code"}
               </span>
             </>
           )}
@@ -850,9 +1020,9 @@ function ServerRow({
         </div>
       )}
 
-      {panel !== "none" && (
+      {visiblePanel !== "none" && (
         <div className="mb-2 ml-9 mr-2 rounded-[10px] border border-border bg-surface-recessed p-3.5">
-          {panel === "setup" ? (
+          {visiblePanel === "setup" ? (
             <SetupCodePanel
               serverId={server.id}
               compact
@@ -919,7 +1089,7 @@ function ConnectAnotherDialog({
           <ClaimField
             layout="dialog"
             autoFocus
-            baseDomain={state.baseDomain}
+            serverUrlTemplate={state.serverUrlTemplate}
             initial={`${state.handle}-desktop`}
             previewLead="This bb will live at"
             buildSubmitLabel={(l) => `Claim ${l || "…"}`}
@@ -940,7 +1110,7 @@ function ConnectAnotherDialog({
           <h4 className="mb-1.5 text-[15px] font-semibold">Pair the new bb</h4>
           <p className="mb-2.5 text-sm text-muted-foreground">
             <code className="font-mono text-xs text-foreground">
-              {server.subdomain}.{state.baseDomain}
+              {server.serverUrl.replace(/^https?:\/\//u, "")}
             </code>{" "}
             is reserved for it.
           </p>
@@ -1004,17 +1174,15 @@ function AccountDashboard({ state }: { state: ServerState }) {
   const [pendingId, setPendingId] = useState<string | null>(null);
 
   const single = state.servers.length === 1;
-  // Poll whenever any bb is still unpaired (first run, or a just-claimed row
-  // waiting for its machine) so the row flips to Online without a manual reload.
-  const waiting =
-    state.servers.some((s: ServerSummary) => !s.connected) ||
-    (connectOpen && pendingId != null);
+  const refreshIntervalMs = dashboardRefreshIntervalMs(
+    state.servers,
+    pendingId,
+  );
 
   useEffect(() => {
-    if (!waiting) return;
-    const id = setInterval(() => void router.invalidate(), 3000);
+    const id = setInterval(() => void router.invalidate(), refreshIntervalMs);
     return () => clearInterval(id);
-  }, [waiting, router]);
+  }, [refreshIntervalMs, router]);
 
   // Self-close the connect dialog once the new server pairs.
   useEffect(() => {
@@ -1067,12 +1235,7 @@ function AccountDashboard({ state }: { state: ServerState }) {
           </button>
         </div>
         {state.servers.map((s: ServerSummary) => (
-          <ServerRow
-            key={s.id}
-            server={s}
-            baseDomain={state.baseDomain}
-            autoPair={single}
-          />
+          <ServerRow key={s.id} server={s} autoPair={single} />
         ))}
       </div>
       <div className="mt-3 rounded-xl border border-border bg-card p-2 shadow-sm">
@@ -1115,10 +1278,9 @@ function AccountDashboard({ state }: { state: ServerState }) {
                 <span className="min-w-0 flex-1">
                   {machine.subdomain !== null ? (
                     <span className="block truncate font-mono text-sm font-medium leading-tight">
-                      {machine.subdomain}
-                      <span className="font-normal text-subtle-foreground">
-                        .{state.baseDomain}
-                      </span>
+                      {state.serverUrlTemplate
+                        .replace("{label}", machine.subdomain)
+                        .replace(/^https?:\/\//u, "")}
                     </span>
                   ) : (
                     <span className="block truncate text-sm font-medium leading-tight">
diff --git a/apps/web/src/server/api.test.ts b/apps/web/src/server/api.test.ts
index 0e0a8c6ca8..e4c5fbb833 100644
--- a/apps/web/src/server/api.test.ts
+++ b/apps/web/src/server/api.test.ts
@@ -26,6 +26,7 @@ import {
   getAccountState,
   redeemConnectCode,
   redeemMachineCode,
+  resolveServerUrlTemplate,
   revokeMachineForServerCredential,
   revokeMachine,
 } from "./api.js";
@@ -53,12 +54,32 @@ beforeEach(() => {
   closeTunnel = vi.fn<(subdomain: string) => Promise<void>>(async () => {});
   deps = {
     db,
-    baseDomain: "getbb.app",
     appUrl: "https://getbb.app",
+    serverUrlTemplate: "https://{label}.getbb.app",
     closeTunnel,
   };
 });
 
+describe("resolveServerUrlTemplate", () => {
+  it("accepts the local HTTP port without changing production defaults", () => {
+    expect(resolveServerUrlTemplate(undefined, "getbb.app")).toBe(
+      "https://{label}.getbb.app",
+    );
+    expect(
+      resolveServerUrlTemplate(
+        "http://{label}.bb.localhost:8787",
+        "bb.localhost",
+      ),
+    ).toBe("http://{label}.bb.localhost:8787");
+    expect(() =>
+      resolveServerUrlTemplate("https://example.com/{label}", "example.com"),
+    ).toThrow("under BASE_DOMAIN");
+    expect(() =>
+      resolveServerUrlTemplate("https://{label}.attacker.example", "getbb.app"),
+    ).toThrow("under BASE_DOMAIN");
+  });
+});
+
 afterEach(() => {
   sqlite.close();
 });
@@ -308,6 +329,25 @@ describe("redeemConnectCode (multi-server routing label)", () => {
     expect(result.handle).toBe("sawyer");
     expect(result.tunnelUrl).toBe("wss://sawyer.getbb.app/__tunnel");
   });
+
+  it("returns a ws tunnel URL for local Cloud", async () => {
+    deps.serverUrlTemplate = "http://{label}.bb.localhost:42745";
+    seedUser("u1");
+    await claimHandle(deps, "u1", "sawyer");
+    const primary = db
+      .select()
+      .from(server)
+      .where(eq(server.subdomain, "sawyer"))
+      .get();
+    const minted = await createConnectCode(deps, "u1", {
+      serverId: primary!.id,
+    });
+    if ("error" in minted) throw new Error(minted.error);
+
+    const result = await redeemConnectCode(deps, minted.code);
+    if ("error" in result) throw new Error(result.error);
+    expect(result.tunnelUrl).toBe("ws://sawyer.bb.localhost:42745/__tunnel");
+  });
 });
 
 describe("disconnectServer (server-scoped)", () => {
diff --git a/apps/web/src/server/api.ts b/apps/web/src/server/api.ts
index abdcd3ea6d..fe554ead8b 100644
--- a/apps/web/src/server/api.ts
+++ b/apps/web/src/server/api.ts
@@ -26,16 +26,49 @@ import { generateConnectCode, generateToken, sha256Hex } from "./tokens.js";
  */
 export interface Deps {
   db: ConnectDb;
-  baseDomain: string;
   appUrl: string;
+  serverUrlTemplate: string;
   closeTunnel?: (routingKey: string) => Promise<void>;
 }
 
+export function resolveServerUrlTemplate(
+  value: string | undefined,
+  baseDomain: string,
+): string {
+  const template = value?.trim() || `https://{label}.${baseDomain}`;
+  if (template.split("{label}").length !== 2) {
+    throw new Error("CONNECT_SERVER_URL_TEMPLATE must contain {label} once");
+  }
+  const probe = "bb-label-probe";
+  const url = new URL(template.replace("{label}", probe));
+  if (
+    (url.protocol !== "http:" && url.protocol !== "https:") ||
+    url.username !== "" ||
+    url.password !== "" ||
+    url.pathname !== "/" ||
+    url.search !== "" ||
+    url.hash !== "" ||
+    url.hostname !== `${probe}.${baseDomain}`
+  ) {
+    throw new Error(
+      "CONNECT_SERVER_URL_TEMPLATE must be an HTTP(S) origin under BASE_DOMAIN",
+    );
+  }
+  return `${url.protocol}//{label}.${baseDomain}${url.port ? `:${url.port}` : ""}`;
+}
+
+function serverUrlForLabel(label: string, template: string): string {
+  return template.replace("{label}", label);
+}
+
 export function depsFromEnv(env: Env): Deps {
   return {
     db: drizzle(env.DB),
-    baseDomain: env.BASE_DOMAIN,
     appUrl: env.APP_URL,
+    serverUrlTemplate: resolveServerUrlTemplate(
+      env.CONNECT_SERVER_URL_TEMPLATE,
+      env.BASE_DOMAIN,
+    ),
     closeTunnel: async (routingKey) => {
       const stub = env.TUNNEL_DO.get(env.TUNNEL_DO.idFromName(routingKey));
       const response = await stub.fetch("https://tunnel/__control/close");
@@ -79,7 +112,7 @@ export interface AccountState {
   /** Primary first, then oldest → newest. Empty until a handle is claimed. */
   servers: ServerSummary[];
   appUrl: string;
-  baseDomain: string;
+  serverUrlTemplate: string;
   /** GitHub login for the account footer link; null for pre-column rows. */
   githubLogin: string | null;
   /** Per-account server ceiling, surfaced in the footer as "N of MAX bbs". */
@@ -103,7 +136,7 @@ type ServerRow = typeof server.$inferSelect;
 function toServerSummary(
   srv: ServerRow,
   handle: string,
-  baseDomain: string,
+  serverUrlTemplate: string,
   now: number,
 ): ServerSummary {
   const lastSeenMs = srv.lastSeenAt?.getTime() ?? null;
@@ -121,7 +154,7 @@ function toServerSummary(
     lastSeenAt: lastSeenMs,
     version: srv.version,
     createdAt: srv.createdAt.getTime(),
-    serverUrl: `https://${srv.subdomain}.${baseDomain}`,
+    serverUrl: serverUrlForLabel(srv.subdomain, serverUrlTemplate),
   };
 }
 
@@ -165,7 +198,7 @@ export async function getAccountState(
   deps: Deps,
   userId: string,
 ): Promise<AccountState> {
-  const { db, baseDomain } = deps;
+  const { db, serverUrlTemplate } = deps;
   await retryPendingMachineRevocations(deps, userId);
   const prof = await db
     .select()
@@ -181,7 +214,7 @@ export async function getAccountState(
   const now = Date.now();
   const base = {
     appUrl: deps.appUrl,
-    baseDomain,
+    serverUrlTemplate,
     githubLogin: userRow?.githubLogin ?? null,
     maxServers: MAX_SERVERS_PER_ACCOUNT,
   };
@@ -222,7 +255,7 @@ export async function getAccountState(
     .all();
 
   const servers = serverRows
-    .map((srv) => toServerSummary(srv, prof.handle, baseDomain, now))
+    .map((srv) => toServerSummary(srv, prof.handle, serverUrlTemplate, now))
     .sort((a, b) =>
       a.isPrimary !== b.isPrimary
         ? a.isPrimary
@@ -385,7 +418,7 @@ export async function createServer(
   userId: string,
   rawLabel: string,
 ): Promise<{ ok: true; server: ServerSummary } | { error: CreateServerError }> {
-  const { db, baseDomain } = deps;
+  const { db, serverUrlTemplate } = deps;
   const prof = await db
     .select()
     .from(profile)
@@ -436,7 +469,12 @@ export async function createServer(
   }
   return {
     ok: true,
-    server: toServerSummary(created, prof.handle, baseDomain, Date.now()),
+    server: toServerSummary(
+      created,
+      prof.handle,
+      serverUrlTemplate,
+      Date.now(),
+    ),
   };
 }
 
@@ -457,10 +495,10 @@ export async function createConnectCode(
   userId: string,
   opts: { serverId?: string; reuse?: boolean } = {},
 ): Promise<IssuedCode | { error: string }> {
-  const { db, baseDomain } = deps;
+  const { db, serverUrlTemplate } = deps;
   const srv = await resolveServer(db, userId, opts.serverId);
   if (!srv) return { error: "no-server" };
-  const serverUrl = `https://${srv.subdomain}.${baseDomain}`;
+  const serverUrl = serverUrlForLabel(srv.subdomain, serverUrlTemplate);
   const now = Date.now();
 
   if (opts.reuse) {
@@ -517,7 +555,7 @@ export async function createMachineCode(
 ): Promise<
   { code: string; expiresInMs: number; serverUrl: string } | { error: string }
 > {
-  const { db, baseDomain } = deps;
+  const { db, serverUrlTemplate } = deps;
   const prof = await db
     .select()
     .from(profile)
@@ -559,7 +597,7 @@ export async function createMachineCode(
   return {
     code,
     expiresInMs: CONNECT_CODE_TTL_MS,
-    serverUrl: `https://${srv.subdomain}.${baseDomain}`,
+    serverUrl: serverUrlForLabel(srv.subdomain, serverUrlTemplate),
   };
 }
 
@@ -717,7 +755,7 @@ function rowsChanged(result: unknown): number {
  * Accepts `Deps` (D1 in the worker via `depsFromEnv`, better-sqlite3 in tests).
  */
 export async function redeemConnectCode(
-  deps: Pick<Deps, "db" | "baseDomain">,
+  deps: Pick<Deps, "db" | "serverUrlTemplate">,
   code: string,
 ): Promise<
   | {
@@ -728,7 +766,7 @@ export async function redeemConnectCode(
     }
   | { error: string; status: number }
 > {
-  const { db, baseDomain } = deps;
+  const { db, serverUrlTemplate } = deps;
   const normalized = code.trim().toUpperCase();
   if (!normalized) return { error: "missing-code", status: 400 };
 
@@ -765,19 +803,19 @@ export async function redeemConnectCode(
     .from(server)
     .where(eq(server.id, row.serverId))
     .get();
-  const prof = await db
-    .select()
-    .from(profile)
-    .where(eq(profile.userId, row.userId))
-    .get();
   // Routing label of the redeemed server (not necessarily the account handle).
-  const handle = srv?.subdomain ?? prof?.handle ?? null;
+  const handle = srv?.subdomain ?? null;
+  const serverUrl = handle
+    ? serverUrlForLabel(handle, serverUrlTemplate)
+    : null;
   return {
     credential,
     serverId: row.serverId,
     handle,
     // Keyed by this server's subdomain (which may be non-primary), not the account handle.
-    tunnelUrl: srv ? `wss://${srv.subdomain}.${baseDomain}/__tunnel` : null,
+    tunnelUrl: serverUrl
+      ? `${serverUrl.replace(/^http/u, "ws")}/__tunnel`
+      : null,
   };
 }
 
@@ -786,7 +824,7 @@ export async function redeemConnectCode(
  * creates a machine row, and returns the durable machine credential once.
  */
 export async function redeemMachineCode(
-  deps: Pick<Deps, "db" | "baseDomain">,
+  deps: Pick<Deps, "db" | "serverUrlTemplate">,
   code: string,
 ): Promise<
   | {
@@ -797,7 +835,7 @@ export async function redeemMachineCode(
     }
   | { error: string; status: number }
 > {
-  const { db, baseDomain } = deps;
+  const { db, serverUrlTemplate } = deps;
   const normalized = code.trim().toUpperCase();
   if (!normalized) return { error: "missing-code", status: 400 };
 
@@ -866,6 +904,6 @@ export async function redeemMachineCode(
     credential,
     machineId,
     handle: prof?.handle ?? null,
-    serverUrl: label ? `https://${label}.${baseDomain}` : null,
+    serverUrl: label ? serverUrlForLabel(label, serverUrlTemplate) : null,
   };
 }
diff --git a/apps/web/src/server/auth.ts b/apps/web/src/server/auth.ts
index 0b417223ff..2097915a52 100644
--- a/apps/web/src/server/auth.ts
+++ b/apps/web/src/server/auth.ts
@@ -3,21 +3,28 @@ import { drizzleAdapter } from "@better-auth/drizzle-adapter";
 import { drizzle } from "drizzle-orm/d1";
 import { account, session, user, verification } from "@bb/connect-db";
 import type { Env } from "./env.js";
+import { resolveDevEmailPasswordEnabled } from "./local-auth.js";
 
 export type Auth = ReturnType<typeof createAuth>;
 
 /**
- * better-auth bound to the staging D1 via drizzle. GitHub is the only provider.
+ * better-auth bound to the Cloud D1 via drizzle. Production uses GitHub;
+ * local Cloud additionally enables email/password credentials.
  * Cookies are scoped to `.${BASE_DOMAIN}` so the tunnel gate on
  * `<handle>.${BASE_DOMAIN}` can validate the same session.
  */
 export function createAuth(env: Env) {
   const db = drizzle(env.DB);
+  const appUrl = new URL(env.APP_URL);
+  const devEmailPasswordEnabled = resolveDevEmailPasswordEnabled(env);
+  const subdomainOrigin = `${appUrl.protocol}//*.${env.BASE_DOMAIN}${
+    appUrl.port ? `:${appUrl.port}` : ""
+  }`;
   return betterAuth({
     appName: "bb connect",
     secret: env.BETTER_AUTH_SECRET,
     baseURL: env.APP_URL,
-    trustedOrigins: [env.APP_URL, `https://*.${env.BASE_DOMAIN}`],
+    trustedOrigins: [env.APP_URL, subdomainOrigin],
     // `better-auth` and `@better-auth/drizzle-adapter` resolve to two copies of
     // `@better-auth/core` under pnpm (different peer hashes — workers-types is in
     // one peer set), so the adapter's type is nominally distinct though identical
@@ -26,7 +33,7 @@ export function createAuth(env: Env) {
       provider: "sqlite",
       schema: { user, session, account, verification },
     }) as unknown as Parameters<typeof betterAuth>[0]["database"],
-    emailAndPassword: { enabled: false },
+    emailAndPassword: { enabled: devEmailPasswordEnabled },
     user: {
       additionalFields: {
         githubLogin: { type: "string", required: false, input: false },
diff --git a/apps/web/src/server/cloud-dev-vite.test.ts b/apps/web/src/server/cloud-dev-vite.test.ts
new file mode 100644
index 0000000000..2748d429cf
--- /dev/null
+++ b/apps/web/src/server/cloud-dev-vite.test.ts
@@ -0,0 +1,30 @@
+import { describe, expect, it } from "vitest";
+import { resolveCloudDevViteSettings } from "./cloud-dev-vite.js";
+
+const localEnv = {
+  BB_CLOUD_DEV_STATE_PATH: "/tmp/cloud-dev",
+  BB_CLOUD_DEV_APP_URL: "http://bb.localhost:42745",
+  BB_CLOUD_DEV_SERVER_URL_TEMPLATE: "http://{label}.bb.localhost:42745",
+  BETTER_AUTH_SECRET: "shared-local-secret",
+};
+
+describe("resolveCloudDevViteSettings", () => {
+  it("ignores local Cloud environment variables during builds", () => {
+    expect(resolveCloudDevViteSettings("build", localEnv)).toBeNull();
+  });
+
+  it("configures local auth during the launcher-owned dev server", () => {
+    expect(resolveCloudDevViteSettings("serve", localEnv)).toEqual({
+      persistStatePath: "/tmp/cloud-dev",
+      vars: {
+        APP_URL: "http://bb.localhost:42745",
+        BASE_DOMAIN: "bb.localhost",
+        BETTER_AUTH_SECRET: "shared-local-secret",
+        CONNECT_SERVER_URL_TEMPLATE: "http://{label}.bb.localhost:42745",
+        DEV_EMAIL_PASSWORD_AUTH: "true",
+        GITHUB_CLIENT_ID: "local-cloud-dev-unused",
+        GITHUB_CLIENT_SECRET: "local-cloud-dev-unused",
+      },
+    });
+  });
+});
diff --git a/apps/web/src/server/cloud-dev-vite.ts b/apps/web/src/server/cloud-dev-vite.ts
new file mode 100644
index 0000000000..e19d1c0786
--- /dev/null
+++ b/apps/web/src/server/cloud-dev-vite.ts
@@ -0,0 +1,32 @@
+export interface CloudDevViteSettings {
+  persistStatePath: string;
+  vars: Record<string, string>;
+}
+
+export function resolveCloudDevViteSettings(
+  command: string,
+  env: Record<string, string | undefined>,
+): CloudDevViteSettings | null {
+  if (command !== "serve") return null;
+
+  const persistStatePath = env.BB_CLOUD_DEV_STATE_PATH?.trim();
+  const appUrl = env.BB_CLOUD_DEV_APP_URL?.trim();
+  const serverUrlTemplate = env.BB_CLOUD_DEV_SERVER_URL_TEMPLATE?.trim();
+  const betterAuthSecret = env.BETTER_AUTH_SECRET?.trim();
+  if (!persistStatePath || !appUrl || !serverUrlTemplate || !betterAuthSecret) {
+    return null;
+  }
+
+  return {
+    persistStatePath,
+    vars: {
+      APP_URL: appUrl,
+      BASE_DOMAIN: new URL(appUrl).hostname,
+      BETTER_AUTH_SECRET: betterAuthSecret,
+      CONNECT_SERVER_URL_TEMPLATE: serverUrlTemplate,
+      DEV_EMAIL_PASSWORD_AUTH: "true",
+      GITHUB_CLIENT_ID: "local-cloud-dev-unused",
+      GITHUB_CLIENT_SECRET: "local-cloud-dev-unused",
+    },
+  };
+}
diff --git a/apps/web/src/server/env.ts b/apps/web/src/server/env.ts
index ed3d8d8cf4..83ad25310d 100644
--- a/apps/web/src/server/env.ts
+++ b/apps/web/src/server/env.ts
@@ -5,6 +5,8 @@ export interface Env {
   TUNNEL_DO: DurableObjectNamespace;
   BASE_DOMAIN: string;
   APP_URL: string;
+  CONNECT_SERVER_URL_TEMPLATE?: string;
+  DEV_EMAIL_PASSWORD_AUTH?: string;
   GITHUB_CLIENT_ID: string;
   GITHUB_CLIENT_SECRET: string;
   BETTER_AUTH_SECRET: string;
diff --git a/apps/web/src/server/fns.ts b/apps/web/src/server/fns.ts
index 4a50dec7d3..eecb41a3f0 100644
--- a/apps/web/src/server/fns.ts
+++ b/apps/web/src/server/fns.ts
@@ -14,22 +14,29 @@ import {
 } from "./api.js";
 import { getEnv } from "./env.js";
 import { getSessionUserId } from "./current-user.server.js";
+import { resolveDevEmailPasswordEnabled } from "./local-auth.js";
 
 // The ONLY server module the client route imports. Everything here is a
 // createServerFn, so the client receives RPC stubs and none of the server-only
 // imports (D1, better-auth, cloudflare:workers) land in the client bundle.
 
 export type DashboardState =
-  | { authed: false }
+  | { authed: false; emailPasswordEnabled: boolean }
   | ({ authed: true } & AccountState);
 
 export const getDashboard = createServerFn({ method: "GET" }).handler(
   async (): Promise<DashboardState> => {
+    const env = getEnv();
     const userId = await getSessionUserId();
-    if (!userId) return { authed: false };
+    if (!userId) {
+      return {
+        authed: false,
+        emailPasswordEnabled: resolveDevEmailPasswordEnabled(env),
+      };
+    }
     return {
       authed: true,
-      ...(await getAccountState(depsFromEnv(getEnv()), userId)),
+      ...(await getAccountState(depsFromEnv(env), userId)),
     };
   },
 );
diff --git a/apps/web/src/server/local-auth.test.ts b/apps/web/src/server/local-auth.test.ts
new file mode 100644
index 0000000000..d51142fbfa
--- /dev/null
+++ b/apps/web/src/server/local-auth.test.ts
@@ -0,0 +1,39 @@
+import { describe, expect, it } from "vitest";
+import { resolveDevEmailPasswordEnabled } from "./local-auth.js";
+
+describe("resolveDevEmailPasswordEnabled", () => {
+  it("enables credential auth only on the local Cloud origin", () => {
+    expect(
+      resolveDevEmailPasswordEnabled({
+        APP_URL: "http://bb.localhost:8787",
+        BASE_DOMAIN: "bb.localhost",
+        DEV_EMAIL_PASSWORD_AUTH: "true",
+      }),
+    ).toBe(true);
+
+    expect(
+      resolveDevEmailPasswordEnabled({
+        APP_URL: "https://getbb.app",
+        BASE_DOMAIN: "getbb.app",
+      }),
+    ).toBe(false);
+
+    expect(() =>
+      resolveDevEmailPasswordEnabled({
+        APP_URL: "https://getbb.app",
+        BASE_DOMAIN: "getbb.app",
+        DEV_EMAIL_PASSWORD_AUTH: "true",
+      }),
+    ).toThrow("only allowed for local Cloud development");
+  });
+
+  it("rejects ambiguous flag values", () => {
+    expect(() =>
+      resolveDevEmailPasswordEnabled({
+        APP_URL: "http://bb.localhost:8787",
+        BASE_DOMAIN: "bb.localhost",
+        DEV_EMAIL_PASSWORD_AUTH: "1",
+      }),
+    ).toThrow("must be true when set");
+  });
+});
diff --git a/apps/web/src/server/local-auth.ts b/apps/web/src/server/local-auth.ts
new file mode 100644
index 0000000000..33b597642a
--- /dev/null
+++ b/apps/web/src/server/local-auth.ts
@@ -0,0 +1,29 @@
+import type { Env } from "./env.js";
+
+/** Enable credential auth only for the launcher's local HTTP origin. */
+export function resolveDevEmailPasswordEnabled(
+  env: Pick<Env, "APP_URL" | "BASE_DOMAIN" | "DEV_EMAIL_PASSWORD_AUTH">,
+): boolean {
+  const value = env.DEV_EMAIL_PASSWORD_AUTH?.trim();
+  if (!value) return false;
+  if (value !== "true") {
+    throw new Error("DEV_EMAIL_PASSWORD_AUTH must be true when set");
+  }
+
+  const appUrl = new URL(env.APP_URL);
+  const isLocalOrigin =
+    appUrl.protocol === "http:" &&
+    appUrl.hostname === env.BASE_DOMAIN &&
+    env.BASE_DOMAIN.endsWith(".localhost") &&
+    appUrl.username === "" &&
+    appUrl.password === "" &&
+    appUrl.pathname === "/" &&
+    appUrl.search === "" &&
+    appUrl.hash === "";
+  if (!isLocalOrigin) {
+    throw new Error(
+      "DEV_EMAIL_PASSWORD_AUTH is only allowed for local Cloud development",
+    );
+  }
+  return true;
+}
diff --git a/apps/web/vite.config.ts b/apps/web/vite.config.ts
index 984700df00..7f7ee48585 100644
--- a/apps/web/vite.config.ts
+++ b/apps/web/vite.config.ts
@@ -1,23 +1,46 @@
 import { fileURLToPath } from "node:url";
 import { defineConfig } from "vite";
-import { cloudflare } from "@cloudflare/vite-plugin";
+import {
+  cloudflare,
+  type PluginConfig,
+  type WorkerConfig,
+} from "@cloudflare/vite-plugin";
 import { tanstackStart } from "@tanstack/react-start/plugin/vite";
 import viteReact from "@vitejs/plugin-react";
 import tailwindcss from "@tailwindcss/vite";
+import { resolveCloudDevViteSettings } from "./src/server/cloud-dev-vite.js";
 
-export default defineConfig({
-  resolve: {
-    alias: { "@": fileURLToPath(new URL("./src", import.meta.url)) },
-  },
-  // Dev binds all interfaces so the server is reachable over the tailnet
-  // (see the dev script's --host 0.0.0.0); allow Tailscale MagicDNS names.
-  server: {
-    allowedHosts: [".ts.net"],
-  },
-  plugins: [
-    cloudflare({ viteEnvironment: { name: "ssr" } }),
-    tailwindcss(),
-    tanstackStart(),
-    viteReact(),
-  ],
+export default defineConfig(({ command }) => {
+  const cloudDev = resolveCloudDevViteSettings(command, process.env);
+  const cloudflareConfig: PluginConfig = {
+    viteEnvironment: { name: "ssr" },
+    ...(cloudDev
+      ? {
+          persistState: { path: cloudDev.persistStatePath },
+          config: (config: WorkerConfig) => ({
+            vars: {
+              ...config.vars,
+              ...cloudDev.vars,
+            },
+          }),
+        }
+      : {}),
+  };
+
+  return {
+    resolve: {
+      alias: { "@": fileURLToPath(new URL("./src", import.meta.url)) },
+    },
+    // Dev binds all interfaces so the server is reachable over the tailnet
+    // (see the dev script's --host 0.0.0.0); allow Tailscale MagicDNS names.
+    server: {
+      allowedHosts: [".localhost", ".ts.net"],
+    },
+    plugins: [
+      cloudflare(cloudflareConfig),
+      tailwindcss(),
+      tanstackStart(),
+      viteReact(),
+    ],
+  };
 });
diff --git a/docs/configuration.md b/docs/configuration.md
index f2e4486433..ba4d2314b2 100644
--- a/docs/configuration.md
+++ b/docs/configuration.md
@@ -59,6 +59,14 @@ For the packaged app, prefer `bb-app config`, `bb-app env`, and launcher flags
 over shell variables. The environment remains the internal and deployment
 substrate, and source-development commands still load `.env` files.
 
+For source development, `pnpm dev` automatically injects
+`BB_DEV_CONNECT_BASE_URL=http://bb.localhost:<worktree-cloud-port>`. The
+Connect plugin accepts this loopback origin only when `NODE_ENV=development`
+and uses it only as the unpaired default. Explicit `bb connect --server ...`
+or `--base-url ...` targets take precedence, and packaged/production bb keeps
+the `https://getbb.app` default. This value is launcher-managed, not a
+`bb-app config` setting.
+
 After `bb-app config` writes `~/.bb/config.json` or `bb-app env` writes
 `~/.bb/env.json`, it asks the running local server to reload. If bb is not
 running, the new values apply on the next start. If you edit either file by
diff --git a/docs/debugging-and-qa.md b/docs/debugging-and-qa.md
index 095bf3dc2a..056debcb37 100644
--- a/docs/debugging-and-qa.md
+++ b/docs/debugging-and-qa.md
@@ -30,3 +30,29 @@ Test agents with:
 eval "$(scripts/bb-dev-app env)"
 pnpm bb:dev thread spawn --project proj_personal --provider codex --permission-mode accept-edits --title "Smoke test" --prompt "Reply only with ok." --json
 ```
+
+## Local Cloud
+
+Run the Cloud dashboard and Connect worker against one local D1 database:
+
+```bash
+pnpm cloud:dev
+```
+
+The command applies migrations and prints the dashboard URL. Create a local
+email/password account, claim a handle, create a pairing code, and run the
+displayed `bb connect` command against a bb started with `pnpm dev`. The same
+worktree-specific local origin serves the dashboard at `bb.localhost` and
+routes `<handle>.bb.localhost` through the Connect worker. Email/password auth
+is enabled only for this loopback workflow; production remains GitHub-only.
+`pnpm dev` automatically sets `BB_DEV_CONNECT_BASE_URL` to that worktree's
+local Cloud origin. While the bb is unpaired, Settings → Plugins → Connect
+therefore opens the local dashboard and a pasted code redeems locally. An
+explicit `bb connect --server ...` or `--base-url ...` still wins, so the dev bb
+can still pair with getbb.app.
+Local machine enrollment follows the same origin: local `http:` server URLs
+produce `ws:` machine tunnels and `http:` share URLs, while non-local machine
+enrollment remains HTTPS-only.
+
+Ctrl-C stops the local services. Local D1 state is kept under
+`.wrangler/cloud-dev`.
diff --git a/package.json b/package.json
index 7b24c19717..9a017aaf98 100644
--- a/package.json
+++ b/package.json
@@ -11,6 +11,7 @@
     "cli:prepare": "pnpm exec turbo run build --filter=@bb/scripts --filter=@bb/cli --output-logs=none --log-prefix=none --summarize=false",
     "ensure-native-modules": "node scripts/ensure-native-modules.mjs",
     "dev": "node scripts/ensure-native-modules.mjs && cross-env NODE_ENV=development dotenv -c development -- node --conditions=source --import tsx packages/scripts/src/commands/run-dev.ts",
+    "cloud:dev": "node --conditions=source --import tsx scripts/bb-cloud-dev.mjs",
     "dev:desktop": "scripts/bb-dev-app current --desktop",
     "dev:status": "scripts/bb-dev-app status",
     "dev:restart": "cross-env NODE_ENV=development node --conditions=source --import tsx packages/scripts/src/commands/request-dev-restart.ts both",
@@ -46,6 +47,7 @@
     "cross-env": "^10.1.0",
     "dotenv-cli": "^11.0.0",
     "esbuild": "^0.28.0",
+    "http-proxy-3": "^1.23.2",
     "prettier": "^3.8.3",
     "rimraf": "^6.1.0",
     "tsx": "^4.23.1",
diff --git a/packages/config/src/runtime.ts b/packages/config/src/runtime.ts
index cfbc43c6b1..6a0f971683 100644
--- a/packages/config/src/runtime.ts
+++ b/packages/config/src/runtime.ts
@@ -6,6 +6,8 @@ export type BbRuntimeMode = "dev" | "prod";
 
 export interface DevPortSet {
   appPort: number;
+  cloudPort: number;
+  cloudWorkerPort: number;
   hostDaemonPort: number;
   serverPort: number;
 }
@@ -88,6 +90,8 @@ const DEV_PORT_BUCKETS = 8_000;
 const DEV_APP_PORT_BASE = 11_000;
 const DEV_SERVER_PORT_BASE = 19_000;
 const DEV_HOST_DAEMON_PORT_BASE = 27_000;
+const DEV_CLOUD_PORT_BASE = 35_000;
+const DEV_CLOUD_WORKER_PORT_BASE = 43_000;
 const DEV_PROCESS_STRIPPED_ENV_KEYS: readonly string[] = [
   "BB_ENVIRONMENT_ID",
   "BB_THREAD_ID",
@@ -134,10 +138,18 @@ function resolvePortOffset(repoRootPath: string): number {
   return Number.parseInt(hash.slice(0, 8), 16) % DEV_PORT_BUCKETS;
 }
 
+function reservePackagedAppPorts(port: number): number {
+  if (port === BB_PROD_SERVER_PORT) return 59_000;
+  if (port === BB_PROD_HOST_DAEMON_PORT) return 59_001;
+  return port;
+}
+
 function resolvePorts(repoRootPath: string): DevPortSet {
   const offset = resolvePortOffset(repoRootPath);
   return {
     appPort: DEV_APP_PORT_BASE + offset,
+    cloudPort: reservePackagedAppPorts(DEV_CLOUD_PORT_BASE + offset),
+    cloudWorkerPort: DEV_CLOUD_WORKER_PORT_BASE + offset,
     hostDaemonPort: DEV_HOST_DAEMON_PORT_BASE + offset,
     serverPort: DEV_SERVER_PORT_BASE + offset,
   };
@@ -305,6 +317,7 @@ export function toDevProcessEnv(args: DevProcessEnvArgs): NodeJS.ProcessEnv {
     ...env,
     BB_DATA_DIR: args.config.dataDir,
     BB_DEV_APP_PORT: String(args.config.ports.appPort),
+    BB_DEV_CONNECT_BASE_URL: `http://bb.localhost:${args.config.ports.cloudPort}`,
     BB_HOST_DAEMON_PORT: String(args.config.ports.hostDaemonPort),
     ...(inheritedSkillsRootPaths.length > 0
       ? { BB_INHERITED_SKILLS_ROOTS: inheritedSkillsRootPaths.join(delimiter) }
diff --git a/packages/connect-client/src/credential.ts b/packages/connect-client/src/credential.ts
index fdb9ddd94a..a155917749 100644
--- a/packages/connect-client/src/credential.ts
+++ b/packages/connect-client/src/credential.ts
@@ -13,6 +13,16 @@ export const connectCredentialSchema = z.object({
 
 export type ConnectCredential = z.infer<typeof connectCredentialSchema>;
 
+export type ConnectPublicProtocol = "http:" | "https:";
+
+/** Local Cloud is HTTP-only; every non-local Connect gate is HTTPS-only. */
+export function connectPublicProtocol(
+  baseDomain: string,
+): ConnectPublicProtocol {
+  const hostname = new URL(`https://${baseDomain}`).hostname;
+  return hostname.endsWith(".localhost") ? "http:" : "https:";
+}
+
 /**
  * Derive the connect cloud apex (`https://getbb.app`) from a server URL
  * (`https://<handle>.getbb.app`) by dropping the handle label.
diff --git a/packages/connect-client/src/index.ts b/packages/connect-client/src/index.ts
index 3248e4d174..e093662c0e 100644
--- a/packages/connect-client/src/index.ts
+++ b/packages/connect-client/src/index.ts
@@ -1,8 +1,10 @@
 export {
   connectCredentialSchema,
+  connectPublicProtocol,
   deriveConnectBaseUrl,
   serverUrlForHandle,
   type ConnectCredential,
+  type ConnectPublicProtocol,
 } from "./credential.js";
 export {
   ConnectListError,
diff --git a/packages/connect-client/test/connect-client.test.ts b/packages/connect-client/test/connect-client.test.ts
index e3e51866e1..7ca278dd57 100644
--- a/packages/connect-client/test/connect-client.test.ts
+++ b/packages/connect-client/test/connect-client.test.ts
@@ -2,6 +2,7 @@ import { describe, expect, it, vi } from "vitest";
 import {
   ConnectListError,
   ConnectMachineRedeemError,
+  connectPublicProtocol,
   deriveConnectBaseUrl,
   listAccountServers,
   redeemMachineCredential,
@@ -26,6 +27,8 @@ describe("connect URL helpers", () => {
     expect(deriveConnectBaseUrl("https://laptop.bb.example:8443")).toBe(
       "https://bb.example:8443",
     );
+    expect(connectPublicProtocol("bb.localhost:42745")).toBe("http:");
+    expect(connectPublicProtocol("getbb.app")).toBe("https:");
   });
 });
 
diff --git a/packages/scripts/test/cloud-dev-proxy.test.mjs b/packages/scripts/test/cloud-dev-proxy.test.mjs
new file mode 100644
index 0000000000..adb685b5ce
--- /dev/null
+++ b/packages/scripts/test/cloud-dev-proxy.test.mjs
@@ -0,0 +1,32 @@
+import { describe, expect, it, vi } from "vitest";
+import { createCloudDevProxy } from "../../../scripts/lib/cloud-dev-proxy.mjs";
+
+describe("local Cloud proxy errors", () => {
+  it.each(["EPIPE", "ECONNRESET"])(
+    "does not crash when a WebSocket client closes with %s",
+    (code) => {
+      const reportError = vi.fn();
+      const proxy = createCloudDevProxy({ reportError });
+      const connection = { destroy: vi.fn() };
+      const error = Object.assign(new Error(`write ${code}`), { code });
+
+      expect(() => proxy.emit("error", error, {}, connection)).not.toThrow();
+      expect(connection.destroy).toHaveBeenCalledOnce();
+      expect(reportError).not.toHaveBeenCalled();
+    },
+  );
+
+  it("reports unexpected proxy errors without crashing", () => {
+    const reportError = vi.fn();
+    const proxy = createCloudDevProxy({ reportError });
+    const connection = { destroy: vi.fn() };
+
+    expect(() =>
+      proxy.emit("error", new Error("unexpected failure"), {}, connection),
+    ).not.toThrow();
+    expect(connection.destroy).toHaveBeenCalledOnce();
+    expect(reportError).toHaveBeenCalledWith(
+      "bb Cloud dev proxy: unexpected failure",
+    );
+  });
+});
diff --git a/packages/scripts/test/cloud-dev-readiness.test.mjs b/packages/scripts/test/cloud-dev-readiness.test.mjs
new file mode 100644
index 0000000000..c90bc17cdf
--- /dev/null
+++ b/packages/scripts/test/cloud-dev-readiness.test.mjs
@@ -0,0 +1,57 @@
+import { createServer } from "node:http";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { waitForCloudService } from "../../../scripts/lib/cloud-dev-readiness.mjs";
+
+let server;
+
+afterEach(async () => {
+  vi.useRealTimers();
+  await new Promise((resolve) => server?.close(resolve) ?? resolve());
+  server = undefined;
+});
+
+describe("local Cloud readiness", () => {
+  it("sends the routing Host header through a real Node HTTP request", async () => {
+    let receivedHost;
+    server = createServer((request, response) => {
+      receivedHost = request.headers.host;
+      response.writeHead(204).end();
+    });
+    await new Promise((resolve) => server.listen(0, "127.0.0.1", resolve));
+    const address = server.address();
+    if (typeof address !== "object" || address === null) {
+      throw new Error("test server did not bind a TCP port");
+    }
+
+    await waitForCloudService({
+      url: `http://127.0.0.1:${address.port}/dashboard`,
+      host: "bb.localhost:42745",
+      serviceExited: () => false,
+    });
+
+    expect(receivedHost).toBe("bb.localhost:42745");
+  });
+
+  it("backs off after a 500 response", async () => {
+    vi.useFakeTimers();
+    const requestImpl = vi
+      .fn()
+      .mockResolvedValueOnce(500)
+      .mockResolvedValueOnce(204);
+
+    const ready = waitForCloudService({
+      url: "http://127.0.0.1:42745/dashboard",
+      host: "bb.localhost:42745",
+      serviceExited: () => false,
+      timeoutMs: 1_000,
+      retryDelayMs: 250,
+      requestImpl,
+    });
+    await vi.advanceTimersByTimeAsync(249);
+    expect(requestImpl).toHaveBeenCalledTimes(1);
+    await vi.advanceTimersByTimeAsync(1);
+    await ready;
+
+    expect(requestImpl).toHaveBeenCalledTimes(2);
+  });
+});
diff --git a/packages/scripts/test/dev-instance-expectations.ts b/packages/scripts/test/dev-instance-expectations.ts
index 2a35e92448..6dab6a75a6 100644
--- a/packages/scripts/test/dev-instance-expectations.ts
+++ b/packages/scripts/test/dev-instance-expectations.ts
@@ -3,6 +3,8 @@ import { isAbsolute, join, relative } from "node:path";
 
 export interface ExpectedDevPortSet {
   appPort: number;
+  cloudPort: number;
+  cloudWorkerPort: number;
   hostDaemonPort: number;
   serverPort: number;
 }
@@ -26,10 +28,18 @@ function expectedPortOffset(repoRoot: string): number {
   );
 }
 
+function reservePackagedAppPorts(port: number): number {
+  if (port === 38_886) return 59_000;
+  if (port === 38_887) return 59_001;
+  return port;
+}
+
 export function expectedDevPorts(repoRoot: string): ExpectedDevPortSet {
   const offset = expectedPortOffset(repoRoot);
   return {
     appPort: 11_000 + offset,
+    cloudPort: reservePackagedAppPorts(35_000 + offset),
+    cloudWorkerPort: 43_000 + offset,
     hostDaemonPort: 27_000 + offset,
     serverPort: 19_000 + offset,
   };
diff --git a/packages/scripts/test/run-dev.test.ts b/packages/scripts/test/run-dev.test.ts
index ccd2075f7f..5af4dbc75a 100644
--- a/packages/scripts/test/run-dev.test.ts
+++ b/packages/scripts/test/run-dev.test.ts
@@ -57,7 +57,7 @@ describe("run-dev", () => {
     expect(config.dataDir).toBe(expectedDevDataDir({ homeDir, repoRoot }));
     expect(config.ports).toEqual(expectedDevPorts(repoRoot));
     expect(config.serverUrl).toBe(expectedDevServerUrl(repoRoot));
-    expect(new Set(Object.values(config.ports))).toHaveLength(3);
+    expect(new Set(Object.values(config.ports))).toHaveLength(5);
     expect(Object.values(config.ports)).not.toContain(5173);
     expect(Object.values(config.ports)).not.toContain(3334);
     expect(Object.values(config.ports)).not.toContain(3002);
@@ -65,6 +65,37 @@ describe("run-dev", () => {
     expect(Object.values(config.ports)).not.toContain(38887);
   });
 
+  it("keeps Cloud gateway ports out of the worker band and packaged ports", () => {
+    const rootsByOffset = new Map([
+      [0, "/repo/port-13604"],
+      [1, "/repo/port-3079"],
+      [3886, "/repo/port-3186"],
+      [3887, "/repo/port-6427"],
+      [7998, "/repo/port-57923"],
+      [7999, "/repo/port-7517"],
+    ]);
+    const portsByOffset = new Map(
+      [...rootsByOffset].map(([offset, repoRoot]) => [
+        offset,
+        resolveDevInstanceConfig({ homeDir: "/Users/tester", repoRoot }).ports,
+      ]),
+    );
+
+    expect(portsByOffset.get(3886)?.cloudPort).toBe(59000);
+    expect(portsByOffset.get(3887)?.cloudPort).toBe(59001);
+    expect(portsByOffset.get(7998)?.cloudPort).toBe(42998);
+    expect(portsByOffset.get(7999)?.cloudPort).toBe(42999);
+    expect(portsByOffset.get(0)?.cloudWorkerPort).toBe(43000);
+    expect(portsByOffset.get(1)?.cloudWorkerPort).toBe(43001);
+    expect(
+      new Set(
+        [...portsByOffset.values()].flatMap(
+          ({ cloudPort, cloudWorkerPort }) => [cloudPort, cloudWorkerPort],
+        ),
+      ),
+    ).toHaveLength(rootsByOffset.size * 2);
+  });
+
   it("uses the home-relative checkout path for non-managed checkout paths", () => {
     const homeDir = "/Users/tester";
     const repoRoot = "/Users/tester/src/work/bb-feature-copy";
@@ -97,6 +128,9 @@ describe("run-dev", () => {
     expect(env.BB_SERVER_URL).toBe(config.serverUrl);
     expect(env.BB_HOST_DAEMON_PORT).toBe(String(config.ports.hostDaemonPort));
     expect(env.BB_DEV_APP_PORT).toBe(String(config.ports.appPort));
+    expect(env.BB_DEV_CONNECT_BASE_URL).toBe(
+      `http://bb.localhost:${config.ports.cloudPort}`,
+    );
   });
 
   it("inherits parent bb skills for managed worktree dev apps", () => {
diff --git a/packages/templates/src/generated/templates.generated.ts b/packages/templates/src/generated/templates.generated.ts
index acdee3cbbd..7078f2656e 100644
--- a/packages/templates/src/generated/templates.generated.ts
+++ b/packages/templates/src/generated/templates.generated.ts
@@ -50,7 +50,7 @@ export const templateDefinitions = [
   },
   {
     "id": "bbGuideEnvironments",
-    "body": "Environment commands\n\nEnvironments determine where threads run. Multiple threads can share an environment\n(e.g., a coding thread and a review thread in the same worktree).\n\nMaking your repo work with bb:\n\n  Commit a .bb-env-setup.sh script at the repo root when new bb worktrees need\n  repo-specific setup. After bb creates a new managed worktree environment, it\n  looks for .bb-env-setup.sh inside that new workspace. If the file is absent,\n  provisioning continues with no error.\n\n  The script must be tracked by git. A fresh worktree only checks out tracked\n  files, so an untracked .bb-env-setup.sh in your source checkout will not be\n  present and will not run.\n\n  BB runs the hook as `env bash .bb-env-setup.sh` with cwd set to the new\n  workspace. POSIX shell setup scripts are not supported on Windows. The hook\n  inherits the host daemon's sanitized environment: NODE_ENV and every BB_*\n  variable are removed, and bb does not inject BB_PROJECT_ID, BB_ENVIRONMENT_ID,\n  or BB_SOURCE_PATH.\n\n  The hook runs only for newly-created managed worktree environments. It does\n  not run for direct/project-checkout environments, personal scratch workspaces,\n  or reconnecting an existing managed worktree.\n\n  A non-zero exit, timeout, signal, or cancellation fails provisioning and bb\n  removes the new worktree. Keep optional setup steps non-fatal inside the\n  script if the environment should still open. Provisioning progress reports\n  \"Running .bb-env-setup.sh\" and then \".bb-env-setup.sh finished\",\n  \".bb-env-setup.sh failed\", or \".bb-env-setup.sh cancelled\".\n\n  New worktrees do not contain untracked files such as .env.local. To copy\n  them from the source checkout, commit a .worktreeinclude file at the repo\n  root. It uses gitignore syntax: one pattern per line, # for comments, ! to\n  negate an earlier pattern. bb copies each untracked file in the source\n  checkout that matches a pattern:\n\n    .env\n    .env.*\n    !.env.example\n    certs/\n\n  bb copies files only. It follows no symlinks, and it replaces nothing that\n  the worktree already has. The copy runs after `git worktree add` and before\n  .bb-env-setup.sh, so the setup script can read the copied files. A pattern\n  that matches nothing, or a file bb cannot read, is reported in the\n  provisioning transcript and does not fail provisioning.\n\n  Large directories such as node_modules are copied file by file. Install\n  dependencies in .bb-env-setup.sh instead of listing them here.\n\n  For files that customize agent instructions and skills (AGENTS.md,\n  .bb/AGENTS.md, .bb/skills/), run `bb guide agent-configuration`.\n\n  bb environment show <id>                Show environment details (path, branch, status)\n\n  bb environment status <id>              Show workspace status\n    --merge-base-branch <branch>          Include merge-base status\n\n  bb environment branches <id>            List local and remote branches\n    --query <query>                       Filter branch names\n    --limit <count>                       Limit local and remote results\n\n  bb environment paths <id>               Search workspace paths\n    --query <query>                       Fuzzy path query\n    --limit <count>                       Maximum results\n    --files                               Include only files unless combined with --directories\n    --directories                         Include only directories unless combined with --files\n\n  bb environment diff <id>                Show file summary and full git diff\n  bb environment diff-files <id>          List changed-file metadata\n    --target <target>                     uncommitted, branch_committed, all, or commit (required)\n    --merge-base-branch <branch>          Required for branch_committed and all\n    --sha <sha>                           Required for commit\n\n  bb environment diff-file <id>           Read one side of a changed file\n    --target <target>                     Diff target (required)\n    --path <path>                         Repository-relative path (required)\n    --side <old|new>                      File side (required)\n    --merge-base-ref <sha>                Required for branch_committed and all\n    --sha <sha>                           Required for commit\n\n  bb environment diff-patch <id>          Fetch selected file patches\n    --target <target>                     Diff target (required)\n    --path <path>                         Changed path; repeat for multiple files (required)\n    --merge-base-branch <branch>          Required for branch_committed and all\n    --sha <sha>                           Required for commit\n\n  bb environment update <id>              Update environment metadata\n    --merge-base-branch <branch>          Set merge-base branch override\n    --clear-merge-base-branch             Clear merge-base override\n    --name <name>                         Set display name\n    --clear-name                          Clear display name\n\n  bb environment commit <id>              Create a commit in the environment\n\n  bb environment squash-merge <id>        Squash-merge into a target branch\n    --merge-base-branch <branch>          Target branch (required)\n\n  bb environment archive-threads <id>     Archive all threads in an environment\n\n  bb environment pull-request show <id>   Inspect a pull request\n  bb environment pull-request ready <id>  Mark a pull request ready\n  bb environment pull-request draft <id>  Convert a pull request to draft\n  bb environment pull-request merge <id>  Merge a pull request\n    --method <method>                     merge, squash, or rebase\n\nEvery inspection command accepts an arbitrary environment ID and supports\n`--json`. Non-git status/diff responses are reported explicitly. `diff-file`\nprints UTF-8 content directly and labels base64 binary content; diff and patch\ntruncation markers are preserved.\n\nRemote access (bb connect):\n\n  Expose this bb server at <handle>.getbb.app so you can reach it from any\n  browser. Claim a handle at https://getbb.app, copy the connect command it\n  generates, then run it here to\n  pair:\n\n  bb connect --code <code> --server https://<handle>.getbb.app\n    --code <code>          One-time pairing code from the dashboard\n    --server <url>         https://<handle>.getbb.app (from the dashboard)\n\n  Pairing returns immediately: the bb SERVER redeems the code, stores the\n  credential, and holds the tunnel itself — so it stays up as long as bb is\n  running and reconnects on restart (no foreground process).\n  Without an installed bb, pair via npm:\n  `npx -p bb-app@latest bb connect --code <code> --server <url>`.\n\n  bb connect status                       Show the server's connect status\n  bb connect off                          Disconnect and forget the pairing\n  bb connect expose <port> [--host <name-or-id>]    Share a host's HTTP port\n  bb connect unexpose <port> [--host <name-or-id>]  Stop sharing on that host\n  bb connect shares [--host <name-or-id>]           List that host's shares\n  bb connect servers                      List every bb on this account (handle, url, live)\n\n  Port sharing works from threads on any enrolled host. In a thread,\n  `bb connect expose <port>` resolves the thread environment's host; outside a\n  thread it defaults to the server host. `--host <name-or-id>` overrides that\n  choice for expose, unexpose, and shares. Server-host URLs use\n  `https://<server-label>--<port>.getbb.app`; machine-host URLs use\n  `https://<machine-label>--<port>.getbb.app` and proxy directly through that\n  machine's daemon. Access is owner-session-gated — only viewers signed into\n  the owner's getbb.app account can open the URL; it is not a public internet\n  link. Agents should run expose from the thread that started the server, share\n  the returned URL, and unexpose from the same thread when it stops.\n  `bb connect status` shows all shares with host + URL. `shares --json` returns\n  the resolved `host` and rows with `hostId`, `hostName`, `port`, and `url`.\n\n  Remote access is owned by the builtin \"connect\" plugin (Plugins → connect\n  shows the URL, QR code, and shared ports). Disabling the plugin\n  (`bb plugin disable connect`) cuts off all remote access; re-enable with\n  `bb plugin enable connect`.",
+    "body": "Environment commands\n\nEnvironments determine where threads run. Multiple threads can share an environment\n(e.g., a coding thread and a review thread in the same worktree).\n\nMaking your repo work with bb:\n\n  Commit a .bb-env-setup.sh script at the repo root when new bb worktrees need\n  repo-specific setup. After bb creates a new managed worktree environment, it\n  looks for .bb-env-setup.sh inside that new workspace. If the file is absent,\n  provisioning continues with no error.\n\n  The script must be tracked by git. A fresh worktree only checks out tracked\n  files, so an untracked .bb-env-setup.sh in your source checkout will not be\n  present and will not run.\n\n  BB runs the hook as `env bash .bb-env-setup.sh` with cwd set to the new\n  workspace. POSIX shell setup scripts are not supported on Windows. The hook\n  inherits the host daemon's sanitized environment: NODE_ENV and every BB_*\n  variable are removed, and bb does not inject BB_PROJECT_ID, BB_ENVIRONMENT_ID,\n  or BB_SOURCE_PATH.\n\n  The hook runs only for newly-created managed worktree environments. It does\n  not run for direct/project-checkout environments, personal scratch workspaces,\n  or reconnecting an existing managed worktree.\n\n  A non-zero exit, timeout, signal, or cancellation fails provisioning and bb\n  removes the new worktree. Keep optional setup steps non-fatal inside the\n  script if the environment should still open. Provisioning progress reports\n  \"Running .bb-env-setup.sh\" and then \".bb-env-setup.sh finished\",\n  \".bb-env-setup.sh failed\", or \".bb-env-setup.sh cancelled\".\n\n  New worktrees do not contain untracked files such as .env.local. To copy\n  them from the source checkout, commit a .worktreeinclude file at the repo\n  root. It uses gitignore syntax: one pattern per line, # for comments, ! to\n  negate an earlier pattern. bb copies each untracked file in the source\n  checkout that matches a pattern:\n\n    .env\n    .env.*\n    !.env.example\n    certs/\n\n  bb copies files only. It follows no symlinks, and it replaces nothing that\n  the worktree already has. The copy runs after `git worktree add` and before\n  .bb-env-setup.sh, so the setup script can read the copied files. A pattern\n  that matches nothing, or a file bb cannot read, is reported in the\n  provisioning transcript and does not fail provisioning.\n\n  Large directories such as node_modules are copied file by file. Install\n  dependencies in .bb-env-setup.sh instead of listing them here.\n\n  For files that customize agent instructions and skills (AGENTS.md,\n  .bb/AGENTS.md, .bb/skills/), run `bb guide agent-configuration`.\n\n  bb environment show <id>                Show environment details (path, branch, status)\n\n  bb environment status <id>              Show workspace status\n    --merge-base-branch <branch>          Include merge-base status\n\n  bb environment branches <id>            List local and remote branches\n    --query <query>                       Filter branch names\n    --limit <count>                       Limit local and remote results\n\n  bb environment paths <id>               Search workspace paths\n    --query <query>                       Fuzzy path query\n    --limit <count>                       Maximum results\n    --files                               Include only files unless combined with --directories\n    --directories                         Include only directories unless combined with --files\n\n  bb environment diff <id>                Show file summary and full git diff\n  bb environment diff-files <id>          List changed-file metadata\n    --target <target>                     uncommitted, branch_committed, all, or commit (required)\n    --merge-base-branch <branch>          Required for branch_committed and all\n    --sha <sha>                           Required for commit\n\n  bb environment diff-file <id>           Read one side of a changed file\n    --target <target>                     Diff target (required)\n    --path <path>                         Repository-relative path (required)\n    --side <old|new>                      File side (required)\n    --merge-base-ref <sha>                Required for branch_committed and all\n    --sha <sha>                           Required for commit\n\n  bb environment diff-patch <id>          Fetch selected file patches\n    --target <target>                     Diff target (required)\n    --path <path>                         Changed path; repeat for multiple files (required)\n    --merge-base-branch <branch>          Required for branch_committed and all\n    --sha <sha>                           Required for commit\n\n  bb environment update <id>              Update environment metadata\n    --merge-base-branch <branch>          Set merge-base branch override\n    --clear-merge-base-branch             Clear merge-base override\n    --name <name>                         Set display name\n    --clear-name                          Clear display name\n\n  bb environment commit <id>              Create a commit in the environment\n\n  bb environment squash-merge <id>        Squash-merge into a target branch\n    --merge-base-branch <branch>          Target branch (required)\n\n  bb environment archive-threads <id>     Archive all threads in an environment\n\n  bb environment pull-request show <id>   Inspect a pull request\n  bb environment pull-request ready <id>  Mark a pull request ready\n  bb environment pull-request draft <id>  Convert a pull request to draft\n  bb environment pull-request merge <id>  Merge a pull request\n    --method <method>                     merge, squash, or rebase\n\nEvery inspection command accepts an arbitrary environment ID and supports\n`--json`. Non-git status/diff responses are reported explicitly. `diff-file`\nprints UTF-8 content directly and labels base64 binary content; diff and patch\ntruncation markers are preserved.\n\nRemote access (bb connect):\n\n  Expose this bb server at <handle>.getbb.app so you can reach it from any\n  browser. Claim a handle at https://getbb.app, copy the connect command it\n  generates, then run it here to\n  pair:\n\n  bb connect --code <code> --server https://<handle>.getbb.app\n    --code <code>          One-time pairing code from the dashboard\n    --server <url>         https://<handle>.getbb.app (from the dashboard)\n\n  Pairing returns immediately: the bb SERVER redeems the code, stores the\n  credential, and holds the tunnel itself — so it stays up as long as bb is\n  running and reconnects on restart (no foreground process).\n  Without an installed bb, pair via npm:\n  `npx -p bb-app@latest bb connect --code <code> --server <url>`.\n\n  In a source checkout, `pnpm dev` automatically points the unpaired Connect\n  settings and code-only pairing at that worktree's local Cloud origin through\n  `BB_DEV_CONNECT_BASE_URL`. Explicit `--server` and `--base-url` targets still\n  win, so the dev bb can also pair with getbb.app.\n\n  bb connect status                       Show the server's connect status\n  bb connect off                          Disconnect and forget the pairing\n  bb connect expose <port> [--host <name-or-id>]    Share a host's HTTP port\n  bb connect unexpose <port> [--host <name-or-id>]  Stop sharing on that host\n  bb connect shares [--host <name-or-id>]           List that host's shares\n  bb connect servers                      List every bb on this account (handle, url, live)\n\n  Port sharing works from threads on any enrolled host. In a thread,\n  `bb connect expose <port>` resolves the thread environment's host; outside a\n  thread it defaults to the server host. `--host <name-or-id>` overrides that\n  choice for expose, unexpose, and shares. Server-host URLs use\n  `https://<server-label>--<port>.getbb.app`; machine-host URLs use\n  `https://<machine-label>--<port>.getbb.app` and proxy directly through that\n  machine's daemon. Access is owner-session-gated — only viewers signed into\n  the owner's getbb.app account can open the URL; it is not a public internet\n  link. Agents should run expose from the thread that started the server, share\n  the returned URL, and unexpose from the same thread when it stops.\n  `bb connect status` shows all shares with host + URL. `shares --json` returns\n  the resolved `host` and rows with `hostId`, `hostName`, `port`, and `url`.\n\n  Remote access is owned by the builtin \"connect\" plugin (Plugins → connect\n  shows the URL, QR code, and shared ports). Disabling the plugin\n  (`bb plugin disable connect`) cuts off all remote access; re-enable with\n  `bb plugin enable connect`.",
     "fileName": "bb-guide-environments.md",
     "kind": "instruction",
     "title": "bb Guide — Environments",
diff --git a/packages/templates/src/templates/bb-guide-environments.md b/packages/templates/src/templates/bb-guide-environments.md
index d205fa2375..989676af55 100644
--- a/packages/templates/src/templates/bb-guide-environments.md
+++ b/packages/templates/src/templates/bb-guide-environments.md
@@ -135,6 +135,11 @@ Remote access (bb connect):
   Without an installed bb, pair via npm:
   `npx -p bb-app@latest bb connect --code <code> --server <url>`.
 
+  In a source checkout, `pnpm dev` automatically points the unpaired Connect
+  settings and code-only pairing at that worktree's local Cloud origin through
+  `BB_DEV_CONNECT_BASE_URL`. Explicit `--server` and `--base-url` targets still
+  win, so the dev bb can also pair with getbb.app.
+
   bb connect status                       Show the server's connect status
   bb connect off                          Disconnect and forget the pairing
   bb connect expose <port> [--host <name-or-id>]    Share a host's HTTP port
diff --git a/plugins/connect/app.test.tsx b/plugins/connect/app.test.tsx
index 673be1087d..996a6201ab 100644
--- a/plugins/connect/app.test.tsx
+++ b/plugins/connect/app.test.tsx
@@ -58,6 +58,22 @@ describe("connect settings section", () => {
     expect(app.settingsSections[0]?.title).toBeUndefined();
   });
 
+  it("uses the local Cloud dashboard supplied by the server", async () => {
+    const dashboardUrl = "http://bb.localhost:42745/dashboard";
+    const slot = renderSlot(
+      app.settingsSections[0]!,
+      {},
+      { rpc: { status: () => status({ dashboardUrl }) } },
+    );
+
+    const link = (await slot.findByRole("link", {
+      name: "Get a connect code",
+    })) as HTMLAnchorElement;
+    expect(link.href).toBe(dashboardUrl);
+    slot.getByText("you.bb.localhost:42745");
+    slot.getByText(/your bb\.localhost:42745 dashboard/);
+  });
+
   it("auto-submits a normalized 4-4 code and applies live paired status", async () => {
     let currentStatus = status();
     const slot = renderSlot(
diff --git a/plugins/connect/app.tsx b/plugins/connect/app.tsx
index 0fdb8fec92..4868e6755d 100644
--- a/plugins/connect/app.tsx
+++ b/plugins/connect/app.tsx
@@ -78,7 +78,7 @@ const PAIR_ERROR_COPY: Record<PairErrorCode, PairErrorCopy> = {
     tail: " — each code works once.",
   },
   network: {
-    lead: "Couldn't reach getbb.app.",
+    lead: "Couldn't reach the Connect service.",
     linkLabel: "Open the dashboard",
     tail: " — check your connection, then try again.",
   },
@@ -745,12 +745,14 @@ function DisconnectDialog({
   open,
   onOpenChange,
   host,
+  dashboardHost,
   pending,
   onConfirm,
 }: {
   open: boolean;
   onOpenChange: (open: boolean) => void;
   host: string;
+  dashboardHost: string;
   pending: boolean;
   onConfirm: () => void;
 }) {
@@ -765,7 +767,7 @@ function DisconnectDialog({
             <p className="text-sm text-muted-foreground">
               <span className="font-medium text-foreground">{host}</span> will
               stop working on all devices. Re-pairing needs a new code from
-              your getbb.app dashboard.
+              your {dashboardHost} dashboard.
             </p>
             <DialogFooter>
               <Button
@@ -806,12 +808,13 @@ function NotPairedContent({
   dashboardUrl: string;
   onPaired: () => void;
 }) {
+  const dashboardHost = hostOf(dashboardUrl);
   return (
     <div className="space-y-4">
       <p className="text-sm text-muted-foreground">
         Pairing gives this bb a private URL like{" "}
         <span className="rounded bg-surface-recessed px-1.5 py-0.5 font-mono text-xs text-foreground">
-          you.getbb.app
+          you.{dashboardHost}
         </span>
         . Your code and data stay on this machine.
       </p>
@@ -820,7 +823,7 @@ function NotPairedContent({
         <StepNumber value={1} />
         <div className="min-w-0 flex-1 space-y-2">
           <p className="text-sm">
-            Get a one-time connect code from your getbb.app dashboard.
+            Get a one-time connect code from your {dashboardHost} dashboard.
           </p>
           <Button type="button" asChild>
             <a href={dashboardUrl} target="_blank" rel="noreferrer">
@@ -844,8 +847,8 @@ function NotPairedContent({
           name="AlertTriangle"
           className="mt-px size-3.5 shrink-0 opacity-70"
         />
-        Anyone signed in to your getbb.app account gets full control of this
-        bb.
+        Anyone signed in to your {dashboardHost} account gets full control of
+        this bb.
       </p>
     </div>
   );
@@ -971,6 +974,7 @@ function ConnectedContent({
         open={confirmOpen}
         onOpenChange={setConfirmOpen}
         host={host}
+        dashboardHost={hostOf(status.dashboardUrl)}
         pending={disconnecting}
         onConfirm={disconnect}
       />
@@ -1063,6 +1067,7 @@ function ReconnectingContent({
         open={confirmOpen}
         onOpenChange={setConfirmOpen}
         host={host}
+        dashboardHost={hostOf(status.dashboardUrl)}
         pending={disconnecting}
         onConfirm={disconnect}
       />
diff --git a/plugins/connect/src/connect.test.ts b/plugins/connect/src/connect.test.ts
index 50a2f35e59..87ad9821ef 100644
--- a/plugins/connect/src/connect.test.ts
+++ b/plugins/connect/src/connect.test.ts
@@ -15,6 +15,7 @@ import {
 import { deriveConnectBaseUrl, serverUrlForHandle } from "@bb/connect-client";
 import {
   parseSharePort,
+  machineSharePublicUrl,
   SharePortError,
   ShareRegistry,
   sharePublicUrl,
@@ -24,6 +25,10 @@ import {
 import { CREDENTIAL_KV_KEY } from "./credential.js";
 import plugin from "./server.js";
 import { ConnectTunnel } from "./tunnel.js";
+import {
+  DEFAULT_CONNECT_BASE_URL,
+  resolveDefaultConnectBaseUrl,
+} from "./redeem.js";
 import type { ConnectStatus } from "./types.js";
 import { ShareHostResolver } from "./hosts.js";
 
@@ -84,6 +89,44 @@ describe("deriveConnectBaseUrl", () => {
   });
 });
 
+describe("resolveDefaultConnectBaseUrl", () => {
+  it("uses the local Cloud origin only in development", () => {
+    expect(
+      resolveDefaultConnectBaseUrl({
+        NODE_ENV: "development",
+        BB_DEV_CONNECT_BASE_URL: "http://bb.localhost:42745/",
+      }),
+    ).toBe("http://bb.localhost:42745");
+    expect(
+      resolveDefaultConnectBaseUrl({
+        NODE_ENV: "production",
+        BB_DEV_CONNECT_BASE_URL: "http://bb.localhost:42745",
+      }),
+    ).toBe(DEFAULT_CONNECT_BASE_URL);
+    expect(resolveDefaultConnectBaseUrl({ NODE_ENV: "development" })).toBe(
+      DEFAULT_CONNECT_BASE_URL,
+    );
+  });
+
+  it("rejects non-local or non-origin development values", () => {
+    for (const value of [
+      "https://bb.localhost:42745",
+      "http://getbb.app:42745",
+      "http://bb.localhost:42745/dashboard",
+      "not a url",
+    ]) {
+      expect(() =>
+        resolveDefaultConnectBaseUrl({
+          NODE_ENV: "development",
+          BB_DEV_CONNECT_BASE_URL: value,
+        }),
+      ).toThrow(
+        "BB_DEV_CONNECT_BASE_URL must be an http://bb.localhost:<port> origin",
+      );
+    }
+  });
+});
+
 describe("serverUrlForHandle", () => {
   it("prepends the handle label to the apex", () => {
     expect(serverUrlForHandle("https://getbb.app", "sawyer")).toBe(
@@ -162,6 +205,15 @@ describe("sharePublicUrl", () => {
       ),
     ).toBe("https://sawyer-desktop--8000.getbb.app");
   });
+
+  it("uses HTTP and the local port for machine shares in local Cloud", () => {
+    expect(
+      machineSharePublicUrl(
+        { label: "sawyer-air", baseDomain: "bb.localhost:42745" },
+        8000,
+      ),
+    ).toBe("http://sawyer-air--8000.bb.localhost:42745");
+  });
 });
 
 describe("parseSharePort / serverOwnPort", () => {
@@ -680,6 +732,7 @@ describe("ConnectTunnel share activation", () => {
         clear: async () => {},
       },
       shares,
+      defaultBaseUrl: DEFAULT_CONNECT_BASE_URL,
       getLoopbackBaseUrl: () => "http://127.0.0.1:38886",
       log: pluginBb.log,
     });
@@ -740,6 +793,7 @@ describe("ConnectTunnel share activation", () => {
         clear: async () => {},
       },
       shares,
+      defaultBaseUrl: DEFAULT_CONNECT_BASE_URL,
       getLoopbackBaseUrl: () => "http://127.0.0.1:38886",
       log: pluginBb.log,
     });
@@ -1308,6 +1362,7 @@ describe("connect plugin", () => {
       host = undefined;
     }
     vi.unstubAllGlobals();
+    vi.unstubAllEnvs();
   });
 
   it("starts unpaired — a healthy state, not needs-configuration", async () => {
@@ -1330,6 +1385,56 @@ describe("connect plugin", () => {
     expect(harness.needsConfigurationMessages).toEqual([]);
   });
 
+  it("uses the worktree-local Cloud for unpaired development", async () => {
+    vi.stubEnv("NODE_ENV", "development");
+    vi.stubEnv("BB_DEV_CONNECT_BASE_URL", "http://bb.localhost:59329");
+    const fetchMock = vi.fn(
+      async () =>
+        new Response(
+          JSON.stringify({ credential: "bbcred_local", handle: "sawyer" }),
+          { status: 200 },
+        ),
+    );
+    vi.stubGlobal("fetch", fetchMock);
+    const { harness } = await loadPlugin();
+
+    const before = (await harness.callRpc("status")) as ConnectStatus;
+    expect(before.dashboardUrl).toBe("http://bb.localhost:59329/dashboard");
+
+    const after = (await harness.callRpc("pair", {
+      code: "ABCD",
+    })) as ConnectStatus;
+    expect(fetchMock).toHaveBeenCalledWith(
+      "http://bb.localhost:59329/api/connect/redeem",
+      expect.objectContaining({ method: "POST" }),
+    );
+    expect(after.url).toBe("http://sawyer.bb.localhost:59329");
+  });
+
+  it("lets an explicit production server override the development default", async () => {
+    vi.stubEnv("NODE_ENV", "development");
+    vi.stubEnv("BB_DEV_CONNECT_BASE_URL", "http://bb.localhost:59329");
+    const fetchMock = vi.fn(
+      async () =>
+        new Response(JSON.stringify({ error: "invalid-code" }), {
+          status: 404,
+        }),
+    );
+    vi.stubGlobal("fetch", fetchMock);
+    const { harness } = await loadPlugin();
+
+    await expect(
+      harness.callRpc("pair", {
+        code: "ABCD",
+        server: "https://sawyer.getbb.app",
+      }),
+    ).rejects.toThrow("invalid_code");
+    expect(fetchMock).toHaveBeenCalledWith(
+      "https://getbb.app/api/connect/redeem",
+      expect.objectContaining({ method: "POST" }),
+    );
+  });
+
   it("registers contributeInstructions", async () => {
     const { harness } = await loadPlugin();
     expect(harness.registrations.instructionProvider).not.toBeNull();
@@ -1450,19 +1555,62 @@ describe("connect plugin", () => {
     expect(exposed.url).toBe("http://sawyer-desktop--8000.localhost:59332");
   });
 
-  it("disconnect clears the stored credential", async () => {
+  it("disconnect revokes the Cloud credential and clears it locally", async () => {
+    const fetchMock = vi.fn(async (input: RequestInfo | URL) => {
+      if (String(input).endsWith("/api/connect/redeem")) {
+        return Response.json({
+          credential: "bbcred_x",
+          handle: "sawyer",
+        });
+      }
+      return Response.json({ ok: true });
+    });
+    vi.stubGlobal("fetch", fetchMock);
     const { bb, harness } = await loadPlugin();
-    // Seed a stored credential (as if paired before this load).
-    await bb.storage.kv.set(CREDENTIAL_KV_KEY, {
-      serverUrl: "http://127.0.0.1:59322",
-      handle: "sawyer",
-      credential: "bbcred_x",
+    await harness.callRpc("pair", {
+      code: "ABCD",
+      server: "http://127.0.0.1:59322",
+      baseUrl: "https://getbb.app",
     });
 
     const after = (await harness.callRpc("disconnect")) as ConnectStatus;
     expect(after.paired).toBe(false);
     expect(after.state).toBe("disconnected");
     expect(await bb.storage.kv.get(CREDENTIAL_KV_KEY)).toBeUndefined();
+    expect(fetchMock).toHaveBeenCalledWith(
+      new URL("http://127.0.0.1:59322/api/connect/disconnect"),
+      expect.objectContaining({
+        method: "POST",
+        headers: { "x-bb-connect-machine": "bbcred_x" },
+      }),
+    );
+  });
+
+  it("still disconnects locally when Cloud cannot be reached", async () => {
+    const fetchMock = vi.fn(async (input: RequestInfo | URL) => {
+      if (String(input).endsWith("/api/connect/redeem")) {
+        return Response.json({
+          credential: "bbcred_offline",
+          handle: "sawyer",
+        });
+      }
+      throw new Error("network unavailable");
+    });
+    vi.stubGlobal("fetch", fetchMock);
+    const { bb, harness } = await loadPlugin();
+    await harness.callRpc("pair", {
+      code: "ABCD",
+      server: "http://127.0.0.1:59323",
+      baseUrl: "https://getbb.app",
+    });
+
+    const after = (await harness.callRpc("disconnect")) as ConnectStatus;
+    expect(after.paired).toBe(false);
+    expect(await bb.storage.kv.get(CREDENTIAL_KV_KEY)).toBeUndefined();
+    expect(harness.logEntries).toContainEqual({
+      level: "warn",
+      message: "Cloud disconnect could not be confirmed: network unavailable",
+    });
   });
 
   it("maps a redeem failure to a typed code (no wire text) and does not persist", async () => {
@@ -2156,6 +2304,51 @@ describe("connect plugin", () => {
     );
   });
 
+  it("routes local machine creation and revocation through the unified Cloud origin", async () => {
+    const fetchMock = vi.fn(async (input: RequestInfo | URL) => {
+      const url = String(input);
+      if (url.endsWith("/api/connect/redeem")) {
+        return Response.json({
+          credential: "bbcred_local",
+          handle: "sawyer",
+        });
+      }
+      if (url === "http://bb.localhost:59330/api/connect/machine-code") {
+        return Response.json({
+          code: "ABCD-EFGH",
+          expiresInMs: 600_000,
+          serverUrl: "http://sawyer.bb.localhost:59330",
+        });
+      }
+      if (url === "http://bb.localhost:59330/api/connect/revoke-machine") {
+        return Response.json({ ok: true });
+      }
+      return new Response("not found", { status: 404 });
+    });
+    vi.stubGlobal("fetch", fetchMock);
+    const { harness } = await loadPlugin();
+    await harness.callRpc("pair", {
+      code: "ABCD",
+      server: "http://sawyer.bb.localhost:59330",
+    });
+
+    await expect(harness.callRpc("createMachineCode")).resolves.toMatchObject({
+      code: "ABCD-EFGH",
+      serverUrl: "http://sawyer.bb.localhost:59330",
+    });
+    await expect(
+      harness.callRpc("revokeMachine", { machineId: "machine-local" }),
+    ).resolves.toEqual({ ok: true });
+    expect(fetchMock).toHaveBeenCalledWith(
+      "http://bb.localhost:59330/api/connect/machine-code",
+      expect.objectContaining({ method: "POST" }),
+    );
+    expect(fetchMock).toHaveBeenCalledWith(
+      "http://bb.localhost:59330/api/connect/revoke-machine",
+      expect.objectContaining({ method: "POST" }),
+    );
+  });
+
   it("listAccountServers surfaces unauthorized cleanly on 401", async () => {
     const fetchMock = vi.fn(async (input: RequestInfo | URL) => {
       const url = String(input);
diff --git a/plugins/connect/src/local-loopback.test.ts b/plugins/connect/src/local-loopback.test.ts
new file mode 100644
index 0000000000..89bbe9cfcd
--- /dev/null
+++ b/plugins/connect/src/local-loopback.test.ts
@@ -0,0 +1,16 @@
+import { describe, expect, it } from "vitest";
+import { resolveLocalCloudLoopbackUrl } from "./local-loopback.js";
+
+describe("resolveLocalCloudLoopbackUrl", () => {
+  it("targets Vite only for a local source-development pairing", () => {
+    expect(
+      resolveLocalCloudLoopbackUrl("http://sawyer.localhost:8787", "11001"),
+    ).toBe("http://127.0.0.1:11001");
+    expect(
+      resolveLocalCloudLoopbackUrl("https://sawyer.getbb.app", "11001"),
+    ).toBeNull();
+    expect(
+      resolveLocalCloudLoopbackUrl("http://sawyer.localhost:8787", undefined),
+    ).toBeNull();
+  });
+});
diff --git a/plugins/connect/src/local-loopback.ts b/plugins/connect/src/local-loopback.ts
new file mode 100644
index 0000000000..70b6c3371c
--- /dev/null
+++ b/plugins/connect/src/local-loopback.ts
@@ -0,0 +1,20 @@
+/** Use Vite as the tunneled origin when a source-dev bb pairs locally. */
+export function resolveLocalCloudLoopbackUrl(
+  serverUrl: string | undefined,
+  rawDevAppPort: string | undefined,
+): string | null {
+  if (!serverUrl || !rawDevAppPort) return null;
+  const port = Number(rawDevAppPort);
+  if (!Number.isInteger(port) || port < 1 || port > 65_535) return null;
+
+  let url: URL;
+  try {
+    url = new URL(serverUrl);
+  } catch {
+    return null;
+  }
+  if (url.protocol !== "http:" || !url.hostname.endsWith(".localhost")) {
+    return null;
+  }
+  return `http://127.0.0.1:${port}`;
+}
diff --git a/plugins/connect/src/redeem.ts b/plugins/connect/src/redeem.ts
index acf2869a97..cb3e14ba57 100644
--- a/plugins/connect/src/redeem.ts
+++ b/plugins/connect/src/redeem.ts
@@ -3,6 +3,41 @@
 
 export const DEFAULT_CONNECT_BASE_URL = "https://getbb.app";
 
+/**
+ * Resolve the unpaired Connect apex. Source development may point at the
+ * worktree-local Cloud, but production always keeps the hosted default.
+ */
+export function resolveDefaultConnectBaseUrl(env: NodeJS.ProcessEnv): string {
+  const configured = env.BB_DEV_CONNECT_BASE_URL?.trim();
+  if (env.NODE_ENV !== "development" || !configured) {
+    return DEFAULT_CONNECT_BASE_URL;
+  }
+
+  let url: URL;
+  try {
+    url = new URL(configured);
+  } catch {
+    throw new Error(
+      "BB_DEV_CONNECT_BASE_URL must be an http://bb.localhost:<port> origin",
+    );
+  }
+  if (
+    url.protocol !== "http:" ||
+    url.hostname !== "bb.localhost" ||
+    url.port.length === 0 ||
+    url.username.length > 0 ||
+    url.password.length > 0 ||
+    (url.pathname !== "" && url.pathname !== "/") ||
+    url.search.length > 0 ||
+    url.hash.length > 0
+  ) {
+    throw new Error(
+      "BB_DEV_CONNECT_BASE_URL must be an http://bb.localhost:<port> origin",
+    );
+  }
+  return url.origin;
+}
+
 export interface RedeemedCredential {
   credential: string;
   /**
diff --git a/plugins/connect/src/server.ts b/plugins/connect/src/server.ts
index 4d6907a100..8a4f389c46 100644
--- a/plugins/connect/src/server.ts
+++ b/plugins/connect/src/server.ts
@@ -5,6 +5,8 @@ import { connectRpcContract, createRpcHandlers } from "./rpc.js";
 import { ShareRegistry } from "./shares.js";
 import { ConnectTunnel } from "./tunnel.js";
 import { ShareHostResolver } from "./hosts.js";
+import { resolveLocalCloudLoopbackUrl } from "./local-loopback.js";
+import { resolveDefaultConnectBaseUrl } from "./redeem.js";
 import {
   CONNECT_REALTIME_CHANNEL,
   REMOTE_ACTIVITY_INSTRUCTIONS_MS,
@@ -15,12 +17,17 @@ export default async function plugin(bb: BbPluginApi) {
   // Tunnel is assigned below; ShareRegistry reads the live credential via this.
   let tunnel!: ConnectTunnel;
   const hostResolver = new ShareHostResolver(() => bb.sdk);
+  const getLoopbackBaseUrl = () =>
+    resolveLocalCloudLoopbackUrl(
+      tunnel.getCredential()?.serverUrl,
+      process.env.BB_DEV_APP_PORT,
+    ) ?? bb.server.loopbackBaseUrl;
 
   const shares = new ShareRegistry({
     kv: bb.storage.kv,
     hosts: bb.hosts,
     hostResolver,
-    getLoopbackBaseUrl: () => bb.server.loopbackBaseUrl,
+    getLoopbackBaseUrl,
     getCredential: () => tunnel.getCredential(),
     log: bb.log,
     onChange: () => {
@@ -31,7 +38,8 @@ export default async function plugin(bb: BbPluginApi) {
   tunnel = new ConnectTunnel({
     store,
     shares,
-    getLoopbackBaseUrl: () => bb.server.loopbackBaseUrl,
+    defaultBaseUrl: resolveDefaultConnectBaseUrl(process.env),
+    getLoopbackBaseUrl,
     log: bb.log,
     onStatusChange: (status) =>
       bb.realtime.publish(CONNECT_REALTIME_CHANNEL, status),
diff --git a/plugins/connect/src/shares.ts b/plugins/connect/src/shares.ts
index d5b48ac240..97f38da14d 100644
--- a/plugins/connect/src/shares.ts
+++ b/plugins/connect/src/shares.ts
@@ -12,6 +12,7 @@ import {
   type ShareHostResolver,
 } from "./hosts.js";
 import {
+  connectPublicProtocol,
   deriveConnectBaseUrl,
   type ConnectCredential,
 } from "@bb/connect-client";
@@ -91,7 +92,7 @@ export function machineSharePublicUrl(
   identity: { label: string; baseDomain: string },
   port: number,
 ): string {
-  return `https://${identity.label}--${port}.${identity.baseDomain}`;
+  return `${connectPublicProtocol(identity.baseDomain)}//${identity.label}--${port}.${identity.baseDomain}`;
 }
 
 export function shareLoopbackOrigin(port: number): string {
diff --git a/plugins/connect/src/tunnel-lifecycle.test.ts b/plugins/connect/src/tunnel-lifecycle.test.ts
index 4b252b90ba..fdf349d380 100644
--- a/plugins/connect/src/tunnel-lifecycle.test.ts
+++ b/plugins/connect/src/tunnel-lifecycle.test.ts
@@ -32,6 +32,7 @@ vi.mock("ws", async (importOriginal) => {
 });
 
 import { ConnectTunnel } from "./tunnel.js";
+import { DEFAULT_CONNECT_BASE_URL } from "./redeem.js";
 
 function createTunnelFixture() {
   const fakeHost = createFakePluginHost({
@@ -69,6 +70,7 @@ function createTunnelFixture() {
       clear: clearCredential,
     },
     shares,
+    defaultBaseUrl: DEFAULT_CONNECT_BASE_URL,
     getLoopbackBaseUrl: () => "http://127.0.0.1:38886",
     log: pluginBb.log,
     onStatusChange,
diff --git a/plugins/connect/src/tunnel.ts b/plugins/connect/src/tunnel.ts
index 60569fa502..b2b0a14d96 100644
--- a/plugins/connect/src/tunnel.ts
+++ b/plugins/connect/src/tunnel.ts
@@ -30,11 +30,7 @@ import {
 } from "@bb/connect-client";
 import type { CredentialStore } from "./credential.js";
 import { fetchMachineCode, MachineCodeError } from "./machine-code.js";
-import {
-  asConnectPairError,
-  DEFAULT_CONNECT_BASE_URL,
-  redeemConnectCode,
-} from "./redeem.js";
+import { asConnectPairError, redeemConnectCode } from "./redeem.js";
 import { revokeMachine } from "./revoke-machine.js";
 import {
   ShareRegistry,
@@ -47,9 +43,29 @@ import {
 import type { ShareHost } from "./hosts.js";
 import type { ConnectStateName, ConnectStatus } from "./types.js";
 
+const DISCONNECT_TIMEOUT_MS = 5_000;
+
+async function notifyCloudOfDisconnect(
+  credential: ConnectCredential,
+): Promise<void> {
+  const response = await fetch(
+    new URL("/api/connect/disconnect", credential.serverUrl),
+    {
+      method: "POST",
+      headers: { "x-bb-connect-machine": credential.credential },
+      signal: AbortSignal.timeout(DISCONNECT_TIMEOUT_MS),
+    },
+  );
+  if (!response.ok && response.status !== 401 && response.status !== 403) {
+    throw new Error(`Cloud returned HTTP ${response.status}`);
+  }
+}
+
 export interface ConnectTunnelOptions {
   store: CredentialStore;
   shares: ShareRegistry;
+  /** Connect apex used only while unpaired and when pair has no target. */
+  defaultBaseUrl: string;
   /**
    * The server's own loopback base URL, read lazily (bb.server is
    * bind-gated; the tunnel only needs it once a socket opens).
@@ -117,7 +133,7 @@ export class ConnectTunnel {
       args.baseUrl ??
       (args.serverUrl !== undefined
         ? deriveConnectBaseUrl(args.serverUrl)
-        : DEFAULT_CONNECT_BASE_URL);
+        : this.options.defaultBaseUrl);
     this.pairing = true;
     this.publish();
     try {
@@ -154,13 +170,24 @@ export class ConnectTunnel {
   }
 
   async disconnect(): Promise<ConnectStatus> {
-    this.shareActivationEpoch += 1;
+    const credential = this.credential;
+    this.teardown();
     await this.options.store.clear();
     this.options.shares.clearMachineDeclarations();
     this.credential = null;
-    this.teardown();
     this.lastError = null;
     this.publish();
+    if (credential !== null) {
+      try {
+        await notifyCloudOfDisconnect(credential);
+      } catch (error) {
+        this.options.log.warn(
+          `Cloud disconnect could not be confirmed: ${
+            error instanceof Error ? error.message : String(error)
+          }`,
+        );
+      }
+    }
     return this.status();
   }
 
@@ -245,12 +272,12 @@ export class ConnectTunnel {
     };
   }
 
-  /** getbb.app dashboard URL, derived from the paired base (or the apex). */
+  /** Dashboard URL, derived from the paired base (or the unpaired default). */
   private dashboardUrl(): string {
     const base =
       this.credential !== null
         ? deriveConnectBaseUrl(this.credential.serverUrl)
-        : DEFAULT_CONNECT_BASE_URL;
+        : this.options.defaultBaseUrl;
     return `${base.replace(/\/$/, "")}/dashboard`;
   }
 
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index c6c1a69ae8..590124bf9d 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -20,6 +20,9 @@ importers:
       esbuild:
         specifier: ^0.28.0
         version: 0.28.1
+      http-proxy-3:
+        specifier: ^1.23.2
+        version: 1.23.3
       prettier:
         specifier: ^3.8.3
         version: 3.8.3
@@ -609,6 +612,9 @@ importers:
       '@bb/config':
         specifier: workspace:*
         version: link:../../packages/config
+      '@bb/connect-client':
+        specifier: workspace:*
+        version: link:../../packages/connect-client
       '@bb/domain':
         specifier: workspace:*
         version: link:../../packages/domain
@@ -883,7 +889,7 @@ importers:
         version: typescript@7.0.2
       vitest:
         specifier: ^4.1.1
-        version: 4.1.1(@opentelemetry/api@1.9.1)(@types/node@22.19.10)(jsdom@29.0.1(@noble/hashes@2.0.1))(msw@2.12.14(@types/node@22.19.10)(@typescript/typescript6@6.0.2))(vite@8.0.12(@types/node@22.19.10)(esbuild@0.28.1)(jiti@2.7.0)(tsx@4.23.1)(yaml@2.9.0))
+        version: 4.1.1(@opentelemetry/api@1.9.0)(@types/node@22.19.10)(jsdom@29.0.1(@noble/hashes@2.0.1))(msw@2.12.14(@types/node@22.19.10)(@typescript/typescript6@6.0.2))(vite@8.0.12(@types/node@22.19.10)(esbuild@0.28.1)(jiti@2.7.0)(tsx@4.23.1)(yaml@2.9.0))
 
   apps/web:
     dependencies:
@@ -1215,7 +1221,7 @@ importers:
         version: typescript@7.0.2
       vitest:
         specifier: ^4.1.1
-        version: 4.1.1(@opentelemetry/api@1.9.0)(@types/node@22.19.10)(jsdom@29.0.1(@noble/hashes@2.0.1))(msw@2.12.14(@types/node@22.19.10)(@typescript/typescript6@6.0.2))(vite@8.0.12(@types/node@22.19.10)(esbuild@0.28.1)(jiti@2.7.0)(tsx@4.23.1)(yaml@2.9.0))
+        version: 4.1.1(@opentelemetry/api@1.9.1)(@types/node@22.19.10)(jsdom@29.0.1(@noble/hashes@2.0.1))(msw@2.12.14(@types/node@22.19.10)(@typescript/typescript6@6.0.2))(vite@8.0.12(@types/node@22.19.10)(esbuild@0.28.1)(jiti@2.7.0)(tsx@4.23.1)(yaml@2.9.0))
 
   packages/bb-app:
     dependencies:
@@ -8656,6 +8662,15 @@ packages:
   flatted@3.3.3:
     resolution: {integrity: sha512-GX+ysw4PBCz0PzosHDepZGANEuFCMLrnRTiEy9McGjmkCQYwRq4A/X786G/fjM/+OjsWSU1ZrY5qyARZmO/uwg==}
 
+  follow-redirects@1.16.0:
+    resolution: {integrity: sha512-y5rN/uOsadFT/JfYwhxRS5R7Qce+g3zG97+JrtFZlC9klX/W5hD7iiLzScI4nZqUS7DNUdhPgw4xI8W2LuXlUw==}
+    engines: {node: '>=4.0'}
+    peerDependencies:
+      debug: '*'
+    peerDependenciesMeta:
+      debug:
+        optional: true
+
   foreground-child@3.3.1:
     resolution: {integrity: sha512-gIXjKqtFuWEgzFRJA9WCQeSJLZDjgJUOMCMzxtvFq/37KojM1BFGufqsCy0r4qSQmYLsZYMeyRqzIWOMup03sw==}
     engines: {node: '>=14'}
@@ -8996,6 +9011,10 @@ packages:
     resolution: {integrity: sha512-4FbRdAX+bSdmo4AUFuS0WNiPz8NgFt+r8ThgNWmlrjQjt1Q7ZR9+zTlce2859x4KSXrwIsaeTqDoKQmtP8pLmQ==}
     engines: {node: '>= 0.8'}
 
+  http-proxy-3@1.23.3:
+    resolution: {integrity: sha512-zm8JCrJUwB3Rn0HJypwwDraljDt7YbF+r7Gz0exDRlaT8Yimjs5VRfwug1GrhoasMna1DjwHeEs48+iKxCozyA==}
+    engines: {node: '>=18'}
+
   http-proxy-agent@7.0.2:
     resolution: {integrity: sha512-T1gkAiYYDWYx3V5Bmyu7HcfcvL7mUrTWiM6yOfa3PIphViJ/gFPbvidQ+veqSOHci/PxBcDabeUNCzpOODJZig==}
     engines: {node: '>= 14'}
@@ -17515,6 +17534,10 @@ snapshots:
 
   flatted@3.3.3: {}
 
+  follow-redirects@1.16.0(debug@4.4.3):
+    optionalDependencies:
+      debug: 4.4.3
+
   foreground-child@3.3.1:
     dependencies:
       cross-spawn: 7.0.6
@@ -18023,6 +18046,13 @@ snapshots:
       statuses: 2.0.2
       toidentifier: 1.0.1
 
+  http-proxy-3@1.23.3:
+    dependencies:
+      debug: 4.4.3
+      follow-redirects: 1.16.0(debug@4.4.3)
+    transitivePeerDependencies:
+      - supports-color
+
   http-proxy-agent@7.0.2:
     dependencies:
       agent-base: 7.1.4
diff --git a/scripts/bb-cloud-dev.mjs b/scripts/bb-cloud-dev.mjs
new file mode 100644
index 0000000000..744c2d5ed6
--- /dev/null
+++ b/scripts/bb-cloud-dev.mjs
@@ -0,0 +1,286 @@
+#!/usr/bin/env node
+
+import { spawn, spawnSync } from "node:child_process";
+import { createServer } from "node:http";
+import { createServer as createTcpServer } from "node:net";
+import { mkdir } from "node:fs/promises";
+import path from "node:path";
+import process from "node:process";
+import { fileURLToPath } from "node:url";
+import { resolveCurrentDevInstanceConfig } from "../packages/config/src/runtime.ts";
+import { CLOUD_DEV_HOST_HEADER } from "../apps/connect/src/cloud-dev.ts";
+import { createCloudDevProxy } from "./lib/cloud-dev-proxy.mjs";
+import { waitForCloudService } from "./lib/cloud-dev-readiness.mjs";
+
+const REPO_ROOT = path.resolve(
+  path.dirname(fileURLToPath(import.meta.url)),
+  "..",
+);
+const STATE_DIR = path.join(REPO_ROOT, ".wrangler", "cloud-dev");
+const DEV_SECRET =
+  "6c9e2f41a7d58b30c4e918f267bd5a0c3f1468e2d9a57b04c8f31a6d72e95b40";
+const DEV_BASE_DOMAIN = "bb.localhost";
+const { ports } = resolveCurrentDevInstanceConfig(REPO_ROOT);
+const CLOUD_URL = `http://${DEV_BASE_DOMAIN}:${ports.cloudPort}`;
+const GATEWAY_URL = `http://127.0.0.1:${ports.cloudPort}`;
+const WORKER_URL = `http://127.0.0.1:${ports.cloudWorkerPort}`;
+const webPort = ports.cloudWorkerPort + 8_000;
+const webUrl = `http://127.0.0.1:${webPort}`;
+const SHUTDOWN_GRACE_MS = 5_000;
+const BOLD = process.stdout.isTTY ? "\u001b[1m" : "";
+const RESET = process.stdout.isTTY ? "\u001b[0m" : "";
+const services = new Set();
+let gateway;
+let stopping;
+
+function fail(message) {
+  console.error(`bb Cloud dev: ${message}`);
+  process.exit(1);
+}
+
+function run(args) {
+  const result = spawnSync("pnpm", args, {
+    cwd: REPO_ROOT,
+    env: { ...process.env, CI: "1" },
+    stdio: "inherit",
+  });
+  if (result.error) fail(result.error.message);
+  if (result.status !== 0) fail(`command failed: pnpm ${args.join(" ")}`);
+}
+
+function spawnService(args, env = {}) {
+  const child = spawn("pnpm", args, {
+    cwd: REPO_ROOT,
+    detached: process.platform !== "win32",
+    env: { ...process.env, ...env },
+    stdio: "inherit",
+  });
+  services.add(child);
+  child.once("error", (error) => {
+    services.delete(child);
+    console.error(`bb Cloud dev: ${error.message}`);
+    if (!stopping) void stop(1);
+  });
+  child.once("exit", (code) => {
+    services.delete(child);
+    if (!stopping) void stop(code ?? 1);
+  });
+  return child;
+}
+
+function signalService(child, signal) {
+  if (child.exitCode !== null || child.signalCode !== null) return;
+  try {
+    if (process.platform === "win32" || child.pid === undefined) {
+      child.kill(signal);
+    } else {
+      process.kill(-child.pid, signal);
+    }
+  } catch {
+    // The process may have exited while shutdown was starting.
+  }
+}
+
+async function stopService(child) {
+  if (child.exitCode !== null || child.signalCode !== null) return;
+  const exited = new Promise((resolve) => {
+    child.once("error", resolve);
+    child.once("exit", resolve);
+  });
+  signalService(child, "SIGTERM");
+  const graceful = await Promise.race([
+    exited.then(() => true),
+    new Promise((resolve) =>
+      setTimeout(() => resolve(false), SHUTDOWN_GRACE_MS),
+    ),
+  ]);
+  if (!graceful) {
+    signalService(child, "SIGKILL");
+    await exited;
+  }
+}
+
+function stop(exitCode = 0) {
+  if (stopping) return stopping;
+  stopping = (async () => {
+    if (gateway?.listening) gateway.close();
+    await Promise.all([...services].map((child) => stopService(child)));
+    process.exit(exitCode);
+  })();
+  return stopping;
+}
+
+process.on("SIGINT", () => void stop(0));
+process.on("SIGTERM", () => void stop(0));
+process.on("SIGHUP", () => void stop(0));
+
+function assertPortAvailable(port, label) {
+  return new Promise((resolve, reject) => {
+    const server = createTcpServer();
+    server.once("error", (error) => {
+      reject(
+        new Error(`${label} port ${port} is unavailable: ${error.message}`),
+      );
+    });
+    server.listen(port, "127.0.0.1", () => {
+      server.close((error) => (error ? reject(error) : resolve()));
+    });
+  });
+}
+
+function routeRequest(request) {
+  try {
+    const hostname = new URL(`http://${request.headers.host ?? ""}`).hostname;
+    if (hostname === DEV_BASE_DOMAIN) {
+      delete request.headers[CLOUD_DEV_HOST_HEADER];
+      return { target: webUrl, changeOrigin: false };
+    }
+    const suffix = `.${DEV_BASE_DOMAIN}`;
+    if (hostname.endsWith(suffix)) {
+      const label = hostname.slice(0, -suffix.length);
+      if (label && !label.includes(".")) {
+        request.headers[CLOUD_DEV_HOST_HEADER] = label;
+        return { target: WORKER_URL, changeOrigin: true };
+      }
+    }
+  } catch {
+    // Invalid hosts are rejected below.
+  }
+  return null;
+}
+
+try {
+  await Promise.all([
+    assertPortAvailable(ports.cloudPort, "Cloud gateway"),
+    assertPortAvailable(ports.cloudWorkerPort, "Connect worker"),
+    assertPortAvailable(webPort, "Cloud dashboard"),
+  ]);
+} catch (error) {
+  fail(error instanceof Error ? error.message : String(error));
+}
+
+await mkdir(STATE_DIR, { recursive: true });
+console.log(`Preparing local Cloud data in ${STATE_DIR}`);
+run([
+  "--filter",
+  "@bb/connect",
+  "exec",
+  "wrangler",
+  "d1",
+  "migrations",
+  "apply",
+  "DB",
+  "--local",
+  "--persist-to",
+  STATE_DIR,
+]);
+
+const proxy = createCloudDevProxy();
+gateway = createServer((request, response) => {
+  const route = routeRequest(request);
+  if (route === null) {
+    response.writeHead(404).end("Unknown local Cloud host\n");
+    return;
+  }
+  proxy.web(request, response, route, () => {
+    if (!response.headersSent) response.writeHead(502);
+    response.end("Local Cloud service is starting\n");
+  });
+});
+gateway.on("upgrade", (request, socket, head) => {
+  const route = routeRequest(request);
+  if (route === null) {
+    socket.destroy();
+    return;
+  }
+  proxy.ws(request, socket, head, route, () => socket.destroy());
+});
+
+try {
+  await new Promise((resolve, reject) => {
+    gateway.once("error", reject);
+    gateway.listen(ports.cloudPort, "127.0.0.1", resolve);
+  });
+} catch (error) {
+  console.error(error instanceof Error ? error.message : String(error));
+  await stop(1);
+}
+
+const worker = spawnService([
+  "--filter",
+  "@bb/connect",
+  "exec",
+  "wrangler",
+  "dev",
+  "--port",
+  String(ports.cloudWorkerPort),
+  "--ip",
+  "127.0.0.1",
+  "--persist-to",
+  STATE_DIR,
+  "--var",
+  `BASE_DOMAIN:${DEV_BASE_DOMAIN}`,
+  "--var",
+  `ACCOUNT_APP_URL:${CLOUD_URL}`,
+  "--var",
+  `BETTER_AUTH_SECRET:${DEV_SECRET}`,
+  "--var",
+  "CLOUD_DEV:true",
+  "--show-interactive-dev-session=false",
+]);
+
+const web = spawnService(
+  [
+    "--filter",
+    "@bb/web",
+    "exec",
+    "vite",
+    "dev",
+    "--host",
+    "127.0.0.1",
+    "--port",
+    String(webPort),
+  ],
+  {
+    BB_CLOUD_DEV_APP_URL: CLOUD_URL,
+    BB_CLOUD_DEV_SERVER_URL_TEMPLATE: `http://{label}.${DEV_BASE_DOMAIN}:${ports.cloudPort}`,
+    BB_CLOUD_DEV_STATE_PATH: STATE_DIR,
+    BETTER_AUTH_SECRET: DEV_SECRET,
+    CLOUDFLARE_ENV: "production",
+    CLOUDFLARE_INCLUDE_PROCESS_ENV: "true",
+    GITHUB_CLIENT_ID: "local-cloud-dev-unused",
+    GITHUB_CLIENT_SECRET: "local-cloud-dev-unused",
+    LANDING_POSTHOG_KEY: "local-cloud-dev-unused",
+    RESEND_API_KEY: "local-cloud-dev-unused",
+  },
+);
+
+try {
+  await Promise.all([
+    waitForCloudService({
+      url: `${GATEWAY_URL}/dashboard`,
+      host: `${DEV_BASE_DOMAIN}:${ports.cloudPort}`,
+      serviceExited: () => web.exitCode !== null,
+    }),
+    waitForCloudService({
+      url: `${GATEWAY_URL}/`,
+      host: `probe.${DEV_BASE_DOMAIN}:${ports.cloudPort}`,
+      serviceExited: () => worker.exitCode !== null,
+    }),
+  ]);
+} catch (error) {
+  console.error(error instanceof Error ? error.message : String(error));
+  await stop(1);
+}
+
+console.log(`
+Local bb Cloud is ready at ${BOLD}${CLOUD_URL}/dashboard${RESET}
+
+Claim a handle, generate a pairing code, and run the command shown in the
+dashboard against a bb started with pnpm dev. Local handles use:
+  http://<handle>.${DEV_BASE_DOMAIN}:${ports.cloudPort}
+
+Press Ctrl-C to stop local Cloud.
+`);
+
+await new Promise(() => {});
diff --git a/scripts/lib/cloud-dev-proxy.mjs b/scripts/lib/cloud-dev-proxy.mjs
new file mode 100644
index 0000000000..0a49cc5f56
--- /dev/null
+++ b/scripts/lib/cloud-dev-proxy.mjs
@@ -0,0 +1,22 @@
+import { createProxyServer } from "http-proxy-3";
+
+function isClosedConnectionError(error) {
+  return (
+    error instanceof Error &&
+    "code" in error &&
+    (error.code === "EPIPE" || error.code === "ECONNRESET")
+  );
+}
+
+export function createCloudDevProxy({ reportError = console.error } = {}) {
+  const proxy = createProxyServer({ ws: true });
+  proxy.on("error", (error, _request, connection) => {
+    connection?.destroy?.();
+    if (!isClosedConnectionError(error)) {
+      reportError(
+        `bb Cloud dev proxy: ${error instanceof Error ? error.message : String(error)}`,
+      );
+    }
+  });
+  return proxy;
+}
diff --git a/scripts/lib/cloud-dev-readiness.mjs b/scripts/lib/cloud-dev-readiness.mjs
new file mode 100644
index 0000000000..7d1dfa82bd
--- /dev/null
+++ b/scripts/lib/cloud-dev-readiness.mjs
@@ -0,0 +1,35 @@
+import { get } from "node:http";
+
+function requestStatus(url, host, timeoutMs) {
+  return new Promise((resolve, reject) => {
+    const request = get(url, { headers: { host } }, (response) => {
+      response.resume();
+      resolve(response.statusCode ?? 500);
+    });
+    request.setTimeout(timeoutMs, () => {
+      request.destroy(new Error(`timed out requesting ${host}`));
+    });
+    request.once("error", reject);
+  });
+}
+
+export async function waitForCloudService({
+  url,
+  host,
+  serviceExited,
+  timeoutMs = 30_000,
+  retryDelayMs = 250,
+  requestImpl = requestStatus,
+}) {
+  const deadline = Date.now() + timeoutMs;
+  while (Date.now() < deadline) {
+    if (serviceExited()) throw new Error("Cloud service exited early");
+    try {
+      if ((await requestImpl(url, host, 1_000)) < 500) return;
+    } catch {
+      // Retry transport failures until the shared startup deadline.
+    }
+    await new Promise((resolve) => setTimeout(resolve, retryDelayMs));
+  }
+  throw new Error(`timed out waiting for ${host}`);
+}