diff --git a/apps/web/src/app/(app)/claw/components/ClawOnboardingFakeWalkthrough.tsx b/apps/web/src/app/(app)/claw/components/ClawOnboardingFakeWalkthrough.tsx
index 1cdd0c5e04..3354912b07 100644
--- a/apps/web/src/app/(app)/claw/components/ClawOnboardingFakeWalkthrough.tsx
+++ b/apps/web/src/app/(app)/claw/components/ClawOnboardingFakeWalkthrough.tsx
@@ -67,6 +67,7 @@ const fakeStatus = {
   botVibe: 'Focused, capable, effective',
   botEmoji: '🤖',
   workerUrl: 'https://claw.kilo.ai',
+  controllerCapabilitiesVersion: null,
   name: 'Fake KiloClaw',
   instanceId: 'fake-instance',
   inboundEmailAddress: null,
diff --git a/apps/web/src/app/(app)/claw/components/ClawOnboardingFlow.state.test.ts b/apps/web/src/app/(app)/claw/components/ClawOnboardingFlow.state.test.ts
index f2f729fe2a..dc5d7f1805 100644
--- a/apps/web/src/app/(app)/claw/components/ClawOnboardingFlow.state.test.ts
+++ b/apps/web/src/app/(app)/claw/components/ClawOnboardingFlow.state.test.ts
@@ -48,6 +48,7 @@ function createStatus(status: KiloClawDashboardStatus['status']): KiloClawDashbo
     botVibe: null,
     botEmoji: null,
     workerUrl: 'https://claw.kilo.ai',
+    controllerCapabilitiesVersion: null,
     instanceId: null,
     inboundEmailAddress: null,
     inboundEmailEnabled: false,
diff --git a/apps/web/src/app/(app)/claw/components/withStatusQueryBoundary.test.ts b/apps/web/src/app/(app)/claw/components/withStatusQueryBoundary.test.ts
index 9c478097fa..ebc7df3245 100644
--- a/apps/web/src/app/(app)/claw/components/withStatusQueryBoundary.test.ts
+++ b/apps/web/src/app/(app)/claw/components/withStatusQueryBoundary.test.ts
@@ -41,6 +41,7 @@ const baseStatus: KiloClawDashboardStatus = {
   botVibe: null,
   botEmoji: null,
   workerUrl: 'https://claw.kilo.ai',
+  controllerCapabilitiesVersion: null,
   instanceId: null,
   inboundEmailAddress: 'amber-river-quiet-maple@kiloclaw.ai',
   inboundEmailEnabled: true,
diff --git a/apps/web/src/app/(app)/claw/new/ClawNewClient.state.test.ts b/apps/web/src/app/(app)/claw/new/ClawNewClient.state.test.ts
index e64aaa12db..7d7316a41c 100644
--- a/apps/web/src/app/(app)/claw/new/ClawNewClient.state.test.ts
+++ b/apps/web/src/app/(app)/claw/new/ClawNewClient.state.test.ts
@@ -39,6 +39,7 @@ const baseStatus: KiloClawDashboardStatus = {
   botVibe: null,
   botEmoji: null,
   workerUrl: 'https://claw.kilo.ai',
+  controllerCapabilitiesVersion: null,
   instanceId: 'instance-1',
   inboundEmailAddress: 'amber-river-quiet-maple@kiloclaw.ai',
   inboundEmailEnabled: true,
diff --git a/apps/web/src/lib/config.server.test.ts b/apps/web/src/lib/config.server.test.ts
new file mode 100644
index 0000000000..cf53dd347d
--- /dev/null
+++ b/apps/web/src/lib/config.server.test.ts
@@ -0,0 +1,112 @@
+import { describe, it, expect } from '@jest/globals';
+import { resolveInstanceUrlTemplate } from './config.server';
+
+describe('resolveInstanceUrlTemplate', () => {
+  describe('kill switch (KILOCLAW_INSTANCE_URL_TEMPLATE=legacy)', () => {
+    it('returns empty (legacy routing) when set to the kill-switch sentinel in production', () => {
+      expect(resolveInstanceUrlTemplate('legacy', 'production', 'https://claw.kilo.ai')).toBe('');
+    });
+
+    it('matches the sentinel case-insensitively', () => {
+      expect(resolveInstanceUrlTemplate('Legacy', 'production', 'https://claw.kilo.ai')).toBe('');
+      expect(resolveInstanceUrlTemplate('LEGACY', 'production', 'https://claw.kilo.ai')).toBe('');
+    });
+
+    it('also disables per-instance URLs in dev when set', () => {
+      expect(resolveInstanceUrlTemplate('legacy', 'development', 'http://localhost:8795')).toBe('');
+    });
+
+    it('treats an explicit empty string as "unset" (falls through to defaults), not as a kill switch', () => {
+      // Platform env pipelines often coerce empty values to "unset", so
+      // empty string must not be the rollback signal.
+      expect(resolveInstanceUrlTemplate('', 'production', 'https://claw.kilo.ai')).toBe(
+        'https://{label}.kiloclaw.ai'
+      );
+      expect(resolveInstanceUrlTemplate('', 'development', 'http://localhost:8795')).toBe(
+        'http://{label}.kiloclaw.localhost:8795'
+      );
+    });
+  });
+
+  describe('production defaults', () => {
+    it('defaults to the canonical prod template when no override is set', () => {
+      expect(resolveInstanceUrlTemplate(undefined, 'production', 'https://claw.kilo.ai')).toBe(
+        'https://{label}.kiloclaw.ai'
+      );
+    });
+
+    it('honors an explicit override in production', () => {
+      expect(
+        resolveInstanceUrlTemplate(
+          'https://{label}.preview.kiloclaw.ai',
+          'production',
+          'https://claw.kilo.ai'
+        )
+      ).toBe('https://{label}.preview.kiloclaw.ai');
+    });
+  });
+
+  describe('development / test defaults', () => {
+    it('derives a loopback-parity template from a localhost KILOCLAW_API_URL', () => {
+      expect(resolveInstanceUrlTemplate(undefined, 'development', 'http://localhost:8795')).toBe(
+        'http://{label}.kiloclaw.localhost:8795'
+      );
+    });
+
+    it('derives a loopback-parity template from a 127.0.0.1 KILOCLAW_API_URL', () => {
+      expect(resolveInstanceUrlTemplate(undefined, 'development', 'http://127.0.0.1:8795')).toBe(
+        'http://{label}.kiloclaw.localhost:8795'
+      );
+    });
+
+    it('preserves the port from KILOCLAW_API_URL when non-default', () => {
+      expect(resolveInstanceUrlTemplate(undefined, 'development', 'http://localhost:9999')).toBe(
+        'http://{label}.kiloclaw.localhost:9999'
+      );
+    });
+
+    it('preserves the scheme from KILOCLAW_API_URL', () => {
+      expect(resolveInstanceUrlTemplate(undefined, 'development', 'https://localhost:8795')).toBe(
+        'https://{label}.kiloclaw.localhost:8795'
+      );
+    });
+
+    it('falls back to the wrangler dev port when KILOCLAW_API_URL is missing', () => {
+      expect(resolveInstanceUrlTemplate(undefined, 'development', undefined)).toBe(
+        'http://{label}.kiloclaw.localhost:8795'
+      );
+    });
+
+    it('falls back when KILOCLAW_API_URL is unparsable', () => {
+      expect(resolveInstanceUrlTemplate(undefined, 'development', 'not a url')).toBe(
+        'http://{label}.kiloclaw.localhost:8795'
+      );
+    });
+
+    it('uses the fallback template when KILOCLAW_API_URL points at a non-loopback host', () => {
+      // Remote staging — dev mode with a non-local worker. We don't try
+      // to derive a wildcard host for it; fall back to the loopback
+      // template. Operators who want a real per-instance URL on remote
+      // staging set KILOCLAW_INSTANCE_URL_TEMPLATE explicitly.
+      expect(resolveInstanceUrlTemplate(undefined, 'development', 'https://staging.kilo.ai')).toBe(
+        'http://{label}.kiloclaw.localhost:8795'
+      );
+    });
+
+    it('defaults loopback-parity in test mode too', () => {
+      expect(resolveInstanceUrlTemplate(undefined, 'test', 'http://localhost:8795')).toBe(
+        'http://{label}.kiloclaw.localhost:8795'
+      );
+    });
+
+    it('honors a dev-parity override', () => {
+      expect(
+        resolveInstanceUrlTemplate(
+          'http://{label}.kiloclaw.localhost:8795',
+          'development',
+          'http://localhost:8795'
+        )
+      ).toBe('http://{label}.kiloclaw.localhost:8795');
+    });
+  });
+});
diff --git a/apps/web/src/lib/config.server.ts b/apps/web/src/lib/config.server.ts
index f3bb4df35f..a7ccad9d6f 100644
--- a/apps/web/src/lib/config.server.ts
+++ b/apps/web/src/lib/config.server.ts
@@ -209,6 +209,96 @@ export const KILOCLAW_INTERNAL_API_SECRET = getEnvVariable('KILOCLAW_INTERNAL_AP
 export const KILOCLAW_INBOUND_EMAIL_DOMAIN =
   getEnvVariable('KILOCLAW_INBOUND_EMAIL_DOMAIN') || 'kiloclaw.ai';
 
+/**
+ * Per-instance worker URL template.
+ *
+ * Per-instance URLs are the default in BOTH production and dev/test so a
+ * merge of the name-based routing feature flips them on automatically,
+ * without forcing anyone to edit env files.
+ *
+ * Resolution rules (checked in order):
+ *   1. `KILOCLAW_INSTANCE_URL_TEMPLATE=legacy` (case-insensitive) is the
+ *      explicit **kill switch** — disables per-instance URLs entirely and
+ *      falls back to the single-host `KILOCLAW_API_URL`. Operators can
+ *      roll prod back without a code deploy; devs can disable locally.
+ *      A non-empty sentinel is used (rather than empty string) because
+ *      Vercel / Node env pipelines often coerce empty env entries into
+ *      "unset", making an empty-string rollback unreliable.
+ *   2. A non-empty `KILOCLAW_INSTANCE_URL_TEMPLATE` is used verbatim.
+ *      Must contain `{label}`; missing placeholder is a misconfiguration
+ *      warned about at render time (see `workerUrlForInstance`).
+ *   3. Otherwise in `NODE_ENV=production`, default to the canonical
+ *      `https://{label}.kiloclaw.ai` template.
+ *   4. Otherwise (dev/test) derive a template from `KILOCLAW_API_URL`:
+ *      if `KILOCLAW_API_URL` looks like a loopback URL (`http://localhost:<port>`
+ *      / `http://127.0.0.1:<port>`), emit
+ *      `http://{label}.kiloclaw.localhost:<port>` so the browser
+ *      auto-resolves `*.kiloclaw.localhost` to `127.0.0.1` per RFC 6761.
+ *      If `KILOCLAW_API_URL` is missing or unparsable, fall back to the
+ *      same template with the wrangler dev port (`8795`) — matches
+ *      `.dev.vars.example`.
+ *
+ * When the template ends up set and contains `{label}`, `getStatus`
+ * emits a `workerUrl` pointing at the instance's own virtual host
+ * (derived from its sandboxId) for instances whose
+ * `controllerCapabilitiesVersion >= 2`. Pre-v2 instances keep falling
+ * back to `KILOCLAW_API_URL`.
+ *
+ * Exported as a plain function so it's testable without forcing a
+ * re-import of this entire module (which triggers production-only
+ * validation of unrelated secrets).
+ */
+const DEFAULT_DEV_WRANGLER_PORT = '8795';
+
+/**
+ * Sentinel value for `KILOCLAW_INSTANCE_URL_TEMPLATE` that disables the
+ * per-instance URL pattern entirely. Case-insensitive match. Picked as
+ * a non-empty word because empty env values are unreliable across
+ * Vercel / Node / dotenv pipelines (often dropped or indistinguishable
+ * from "unset"), which would mean the kill switch silently fails open.
+ */
+const KILL_SWITCH_SENTINEL = 'legacy';
+
+function deriveDevTemplateFromWorkerUrl(workerUrl: string | undefined): string {
+  const fallback = `http://{label}.kiloclaw.localhost:${DEFAULT_DEV_WRANGLER_PORT}`;
+  if (!workerUrl) return fallback;
+  try {
+    const parsed = new URL(workerUrl);
+    // Only derive when we're pointed at a loopback dev worker. Anything
+    // else (remote staging, preview domains, etc.) uses the same
+    // fallback — operators can still override explicitly.
+    if (parsed.hostname !== 'localhost' && parsed.hostname !== '127.0.0.1') {
+      return fallback;
+    }
+    const port = parsed.port || DEFAULT_DEV_WRANGLER_PORT;
+    return `${parsed.protocol}//{label}.kiloclaw.localhost:${port}`;
+  } catch {
+    return fallback;
+  }
+}
+
+export function resolveInstanceUrlTemplate(
+  envVar: string | undefined,
+  nodeEnv: string | undefined,
+  workerUrl: string | undefined
+): string {
+  // Explicit kill switch. Empty string falls through to the production
+  // / dev defaults — operators must set `legacy` to disable, not "".
+  if (envVar !== undefined && envVar.toLowerCase() === KILL_SWITCH_SENTINEL) {
+    return '';
+  }
+  // Non-empty explicit override wins.
+  if (envVar !== undefined && envVar !== '') return envVar;
+  if (nodeEnv === 'production') return 'https://{label}.kiloclaw.ai';
+  return deriveDevTemplateFromWorkerUrl(workerUrl);
+}
+
+export const KILOCLAW_INSTANCE_URL_TEMPLATE = resolveInstanceUrlTemplate(
+  process.env.KILOCLAW_INSTANCE_URL_TEMPLATE,
+  process.env.NODE_ENV,
+  KILOCLAW_API_URL
+);
+
 // KiloClaw Early Bird Checkout
 export const STRIPE_KILOCLAW_EARLYBIRD_PRICE_ID = getEnvVariable(
   'STRIPE_KILOCLAW_EARLYBIRD_PRICE_ID'
diff --git a/apps/web/src/lib/kiloclaw/instance-url.test.ts b/apps/web/src/lib/kiloclaw/instance-url.test.ts
new file mode 100644
index 0000000000..3cc97697fd
--- /dev/null
+++ b/apps/web/src/lib/kiloclaw/instance-url.test.ts
@@ -0,0 +1,136 @@
+import { describe, it, expect, jest } from '@jest/globals';
+import { workerUrlForInstance } from './instance-url';
+import { sandboxIdFromUserId, sandboxIdFromInstanceId } from '@kilocode/worker-utils/sandbox-id';
+
+const LEGACY = 'https://claw.kilo.ai';
+const TEMPLATE = 'https://{label}.kiloclaw.ai';
+
+describe('workerUrlForInstance', () => {
+  it('falls back to the legacy URL when the template is unset', () => {
+    const sandboxId = sandboxIdFromInstanceId('550e8400-e29b-41d4-a716-446655440000');
+    expect(
+      workerUrlForInstance({
+        sandboxId,
+        controllerCapabilitiesVersion: 2,
+        template: '',
+        fallback: LEGACY,
+      })
+    ).toBe(LEGACY);
+  });
+
+  it('falls back to the legacy URL and warns once when the template has no {label} placeholder', () => {
+    const sandboxId = sandboxIdFromInstanceId('550e8400-e29b-41d4-a716-446655440000');
+    const warn = jest.spyOn(console, 'warn').mockImplementation(() => {});
+    try {
+      expect(
+        workerUrlForInstance({
+          sandboxId,
+          controllerCapabilitiesVersion: 2,
+          template: 'https://claw.kiloclaw.ai',
+          fallback: LEGACY,
+        })
+      ).toBe(LEGACY);
+      // Subsequent calls with the same misconfiguration must not spam logs.
+      workerUrlForInstance({
+        sandboxId,
+        controllerCapabilitiesVersion: 2,
+        template: 'https://claw.kiloclaw.ai',
+        fallback: LEGACY,
+      });
+      expect(warn).toHaveBeenCalledTimes(1);
+      expect(warn.mock.calls[0][0]).toMatch(/missing the \{label\} placeholder/);
+    } finally {
+      warn.mockRestore();
+    }
+  });
+
+  it('falls back to the legacy URL for pre-v2 instances', () => {
+    const sandboxId = sandboxIdFromInstanceId('550e8400-e29b-41d4-a716-446655440000');
+    expect(
+      workerUrlForInstance({
+        sandboxId,
+        controllerCapabilitiesVersion: null,
+        template: TEMPLATE,
+        fallback: LEGACY,
+      })
+    ).toBe(LEGACY);
+    expect(
+      workerUrlForInstance({
+        sandboxId,
+        controllerCapabilitiesVersion: 1,
+        template: TEMPLATE,
+        fallback: LEGACY,
+      })
+    ).toBe(LEGACY);
+  });
+
+  it('falls back to the legacy URL when sandboxId is null (no-instance sentinel)', () => {
+    expect(
+      workerUrlForInstance({
+        sandboxId: null,
+        controllerCapabilitiesVersion: 2,
+        template: TEMPLATE,
+        fallback: LEGACY,
+      })
+    ).toBe(LEGACY);
+  });
+
+  it('expands the template for instance-keyed sandboxIds on v2+', () => {
+    const sandboxId = sandboxIdFromInstanceId('550e8400-e29b-41d4-a716-446655440000');
+    expect(
+      workerUrlForInstance({
+        sandboxId,
+        controllerCapabilitiesVersion: 2,
+        template: TEMPLATE,
+        fallback: LEGACY,
+      })
+    ).toBe('https://i-550e8400e29b41d4a716446655440000.kiloclaw.ai');
+  });
+
+  it('expands the template for legacy userId sandboxes on v2+', () => {
+    const sandboxId = sandboxIdFromUserId('oauth/google:118234567890');
+    expect(
+      workerUrlForInstance({
+        sandboxId,
+        controllerCapabilitiesVersion: 2,
+        template: TEMPLATE,
+        fallback: LEGACY,
+      })
+    ).toMatch(/^https:\/\/u-[0-9a-v]+\.kiloclaw\.ai$/);
+  });
+
+  it('falls back to the legacy URL when the sandboxId cannot be safely labelled', () => {
+    const overlongSandboxId = sandboxIdFromUserId('a'.repeat(39));
+    expect(
+      workerUrlForInstance({
+        sandboxId: overlongSandboxId,
+        controllerCapabilitiesVersion: 2,
+        template: TEMPLATE,
+        fallback: LEGACY,
+      })
+    ).toBe(LEGACY);
+  });
+
+  it('uses the hardcoded default when fallback is empty', () => {
+    expect(
+      workerUrlForInstance({
+        sandboxId: null,
+        controllerCapabilitiesVersion: 2,
+        template: '',
+        fallback: '',
+      })
+    ).toBe('https://claw.kilo.ai');
+  });
+
+  it('works with dev-parity templates (http + port)', () => {
+    const sandboxId = sandboxIdFromInstanceId('550e8400-e29b-41d4-a716-446655440000');
+    expect(
+      workerUrlForInstance({
+        sandboxId,
+        controllerCapabilitiesVersion: 2,
+        template: 'http://{label}.kiloclaw.localhost:8795',
+        fallback: 'http://localhost:8795',
+      })
+    ).toBe('http://i-550e8400e29b41d4a716446655440000.kiloclaw.localhost:8795');
+  });
+});
diff --git a/apps/web/src/lib/kiloclaw/instance-url.ts b/apps/web/src/lib/kiloclaw/instance-url.ts
new file mode 100644
index 0000000000..8cd01e3026
--- /dev/null
+++ b/apps/web/src/lib/kiloclaw/instance-url.ts
@@ -0,0 +1,70 @@
+/**
+ * Per-instance worker URL minting.
+ *
+ * Returns the dashboard-facing URL the browser should use to talk to a
+ * specific KiloClaw instance.
+ *
+ * When `KILOCLAW_INSTANCE_URL_TEMPLATE` is set (e.g.
+ * `https://{label}.kiloclaw.ai`) AND the instance is on the post-PR1
+ * controller contract (`controllerCapabilitiesVersion >= 2`), the
+ * template is expanded with the sandboxId's hostname label. Otherwise
+ * falls back to the legacy single-host `KILOCLAW_API_URL`.
+ *
+ * The capability gate matters: v1 machines don't have the per-instance
+ * origin in their OpenClaw allowlist, so WebSocket upgrades from the
+ * per-instance host would fail openclaw's exact-match origin check.
+ * Keeping v1 instances on the legacy host until they restart onto v2
+ * avoids a user-visible regression.
+ *
+ * Inputs:
+ *   - `sandboxId`: DO's authoritative sandboxId (null for no-instance sentinel)
+ *   - `controllerCapabilitiesVersion`: from the worker's `getStatus`
+ *     (null → treat as pre-v1, legacy host)
+ *   - `template`: `KILOCLAW_INSTANCE_URL_TEMPLATE` (empty → legacy host)
+ *   - `fallback`: `KILOCLAW_API_URL` (empty → "https://claw.kilo.ai")
+ */
+
+import { hostnameLabelFromSandboxId } from '@kilocode/worker-utils/hostname-label';
+
+const MIN_CAPABILITY_VERSION_FOR_PER_INSTANCE_URL = 2;
+
+const DEFAULT_LEGACY_URL = 'https://claw.kilo.ai';
+
+/**
+ * Process-local guard so the "misconfigured template" warning fires
+ * once per worker/Node process instead of on every getStatus call.
+ * Resets on cold start, which is the right granularity for operator
+ * feedback after a config change.
+ */
+let warnedAboutMissingLabelPlaceholder = false;
+
+export function workerUrlForInstance(params: {
+  sandboxId: string | null;
+  controllerCapabilitiesVersion: number | null;
+  template: string;
+  fallback: string;
+}): string {
+  const { sandboxId, controllerCapabilitiesVersion, template, fallback } = params;
+  const legacyUrl = fallback || DEFAULT_LEGACY_URL;
+
+  if (!template) return legacyUrl;
+  if (!template.includes('{label}')) {
+    // Operator set a template but forgot the placeholder. Silently
+    // falling back to the legacy URL hides the misconfiguration; emit
+    // a one-time warning so it shows up in logs.
+    if (!warnedAboutMissingLabelPlaceholder) {
+      warnedAboutMissingLabelPlaceholder = true;
+      console.warn(
+        '[workerUrlForInstance] KILOCLAW_INSTANCE_URL_TEMPLATE is set but missing the {label} placeholder; falling back to legacy URL'
+      );
+    }
+    return legacyUrl;
+  }
+  if (!sandboxId) return legacyUrl;
+  if ((controllerCapabilitiesVersion ?? 0) < MIN_CAPABILITY_VERSION_FOR_PER_INSTANCE_URL) {
+    return legacyUrl;
+  }
+  const label = hostnameLabelFromSandboxId(sandboxId);
+  if (!label) return legacyUrl;
+  return template.replace('{label}', label);
+}
diff --git a/apps/web/src/lib/kiloclaw/types.ts b/apps/web/src/lib/kiloclaw/types.ts
index fe0a6fb343..8006ba0cf7 100644
--- a/apps/web/src/lib/kiloclaw/types.ts
+++ b/apps/web/src/lib/kiloclaw/types.ts
@@ -225,6 +225,15 @@ export type PlatformStatusResponse = {
   botNature: string | null;
   botVibe: string | null;
   botEmoji: string | null;
+  /**
+   * Version of the controller-configuration contract the running machine
+   * was started with. Bumped by the worker whenever the set of env vars /
+   * config it writes into a machine changes in a way callers care about.
+   * `null` means the instance has never been started under a versioned
+   * contract (treat as pre-v1 / legacy). See
+   * `services/kiloclaw/src/config.ts` (`WORKER_CONTROLLER_CAPABILITIES_VERSION`).
+   */
+  controllerCapabilitiesVersion: number | null;
 };
 
 /** A single registry DO's entries + migration status. */
@@ -594,7 +603,14 @@ export type ChatCredentials = {
 
 /** Combined status returned by tRPC getStatus */
 export type KiloClawDashboardStatus = PlatformStatusResponse & {
-  /** Worker base URL for constructing the "Open" link. Falls back to claw.kilo.ai. */
+  /**
+   * Worker base URL for constructing the "Open" link.
+   *
+   * When `KILOCLAW_INSTANCE_URL_TEMPLATE` is configured and the instance
+   * is on `controllerCapabilitiesVersion >= 2`, this is the per-instance
+   * virtual host (e.g. `https://i-<hex>.kiloclaw.ai`). Otherwise it falls
+   * back to `KILOCLAW_API_URL` (production: `https://claw.kilo.ai`).
+   */
   workerUrl: string;
   name: string | null;
   /** Postgres row ID. Used to construct /i/{instanceId} proxy paths for instance-keyed instances. */
diff --git a/apps/web/src/routers/kiloclaw-router.ts b/apps/web/src/routers/kiloclaw-router.ts
index c5dc52f5a1..a9276d9515 100644
--- a/apps/web/src/routers/kiloclaw-router.ts
+++ b/apps/web/src/routers/kiloclaw-router.ts
@@ -17,7 +17,8 @@ import {
   isValidCustomSecretKey,
   isValidConfigPath,
 } from '@kilocode/kiloclaw-secret-catalog';
-import { KILOCLAW_API_URL } from '@/lib/config.server';
+import { KILOCLAW_API_URL, KILOCLAW_INSTANCE_URL_TEMPLATE } from '@/lib/config.server';
+import { workerUrlForInstance } from '@/lib/kiloclaw/instance-url';
 import { db, type DrizzleTransaction } from '@/lib/drizzle';
 import { insertKiloClawSubscriptionChangeLog } from '@kilocode/db';
 import {
@@ -914,6 +915,7 @@ function createNoInstanceStatus(userId: string, workerUrl: string): KiloClawDash
     botVibe: null,
     botEmoji: null,
     workerUrl,
+    controllerCapabilitiesVersion: null,
     name: null,
     instanceId: null,
     inboundEmailAddress: null,
@@ -2345,10 +2347,13 @@ export const kiloclawRouter = createTRPCRouter({
 
   getStatus: baseProcedure.query(async ({ ctx }) => {
     const instance = await getActiveInstance(ctx.user.id);
-    const workerUrl = KILOCLAW_API_URL || 'https://claw.kilo.ai';
+    const legacyWorkerUrl = KILOCLAW_API_URL || 'https://claw.kilo.ai';
 
     if (!instance) {
-      return createNoInstanceStatus(ctx.user.id, workerUrl);
+      // No instance yet → no sandboxId yet → per-instance URL can't be
+      // minted. Serve the legacy host; the real host kicks in once the
+      // dashboard provisions and re-fetches status.
+      return createNoInstanceStatus(ctx.user.id, legacyWorkerUrl);
     }
 
     const client = new KiloClawInternalClient();
@@ -2357,6 +2362,13 @@ export const kiloclawRouter = createTRPCRouter({
       getInboundEmailAddressForInstance(instance.id),
     ]);
 
+    const workerUrl = workerUrlForInstance({
+      sandboxId: status.sandboxId,
+      controllerCapabilitiesVersion: status.controllerCapabilitiesVersion,
+      template: KILOCLAW_INSTANCE_URL_TEMPLATE,
+      fallback: legacyWorkerUrl,
+    });
+
     return {
       ...status,
       name: instance.name ?? null,
diff --git a/apps/web/src/routers/organizations/organization-kiloclaw-router.ts b/apps/web/src/routers/organizations/organization-kiloclaw-router.ts
index 2f42d95671..f30e970ac2 100644
--- a/apps/web/src/routers/organizations/organization-kiloclaw-router.ts
+++ b/apps/web/src/routers/organizations/organization-kiloclaw-router.ts
@@ -17,7 +17,8 @@ import {
   isValidCustomSecretKey,
   isValidConfigPath,
 } from '@kilocode/kiloclaw-secret-catalog';
-import { KILOCLAW_API_URL } from '@/lib/config.server';
+import { KILOCLAW_API_URL, KILOCLAW_INSTANCE_URL_TEMPLATE } from '@/lib/config.server';
+import { workerUrlForInstance } from '@/lib/kiloclaw/instance-url';
 import { sentryLogger } from '@/lib/utils.server';
 import { db } from '@/lib/drizzle';
 import {
@@ -309,7 +310,7 @@ export const organizationKiloclawRouter = createTRPCRouter({
 
   getStatus: organizationMemberProcedure.query(async ({ ctx, input }) => {
     const instance = await getActiveOrgInstance(ctx.user.id, input.organizationId);
-    const workerUrl = KILOCLAW_API_URL || 'https://claw.kilo.ai';
+    const legacyWorkerUrl = KILOCLAW_API_URL || 'https://claw.kilo.ai';
 
     // No org instance → return a "no instance" sentinel so the frontend
     // renders setup entry points. Without this guard, workerInstanceId(null)
@@ -351,7 +352,8 @@ export const organizationKiloclawRouter = createTRPCRouter({
         botNature: null,
         botVibe: null,
         botEmoji: null,
-        workerUrl,
+        workerUrl: legacyWorkerUrl,
+        controllerCapabilitiesVersion: null,
         name: null,
         instanceId: null,
         inboundEmailAddress: null,
@@ -365,6 +367,13 @@ export const organizationKiloclawRouter = createTRPCRouter({
       getInboundEmailAddressForInstance(instance.id),
     ]);
 
+    const workerUrl = workerUrlForInstance({
+      sandboxId: status.sandboxId,
+      controllerCapabilitiesVersion: status.controllerCapabilitiesVersion,
+      template: KILOCLAW_INSTANCE_URL_TEMPLATE,
+      fallback: legacyWorkerUrl,
+    });
+
     return {
       ...status,
       name: instance.name ?? null,
diff --git a/packages/worker-utils/package.json b/packages/worker-utils/package.json
index 5a9540a46b..8523d8263a 100644
--- a/packages/worker-utils/package.json
+++ b/packages/worker-utils/package.json
@@ -6,6 +6,8 @@
   "exports": {
     ".": "./src/index.ts",
     "./instance-id": "./src/instance-id.ts",
+    "./sandbox-id": "./src/sandbox-id.ts",
+    "./hostname-label": "./src/hostname-label.ts",
     "./redact-headers": "./src/redact-headers.ts",
     "./kiloclaw-billing-observability": "./src/kiloclaw-billing-observability.ts"
   },
diff --git a/services/kiloclaw/src/auth/hostname-label.test.ts b/packages/worker-utils/src/hostname-label.test.ts
similarity index 99%
rename from services/kiloclaw/src/auth/hostname-label.test.ts
rename to packages/worker-utils/src/hostname-label.test.ts
index 961347151f..3197f90612 100644
--- a/services/kiloclaw/src/auth/hostname-label.test.ts
+++ b/packages/worker-utils/src/hostname-label.test.ts
@@ -1,6 +1,6 @@
 import { describe, it, expect } from 'vitest';
 import { sandboxIdFromUserId } from './sandbox-id';
-import { sandboxIdFromInstanceId } from '@kilocode/worker-utils/instance-id';
+import { sandboxIdFromInstanceId } from './instance-id';
 import {
   hostnameLabelFromSandboxId,
   sandboxIdFromHostnameLabel,
diff --git a/packages/worker-utils/src/hostname-label.ts b/packages/worker-utils/src/hostname-label.ts
new file mode 100644
index 0000000000..4f5a59d727
--- /dev/null
+++ b/packages/worker-utils/src/hostname-label.ts
@@ -0,0 +1,240 @@
+/**
+ * Hostname label <-> sandboxId translation for per-instance virtual hosting
+ * on `*.kiloclaw.ai` (or a configured dev-suffix).
+ *
+ * Two instance shapes map to two label prefixes:
+ *
+ *   instance-keyed sandboxId  "ki_{32hex}"       <->  "i-{32hex}"
+ *   legacy sandboxId          base64url(userId)   <->  "u-{base32hex(userId)}"
+ *
+ * Prefix disambiguates the two cases without a database lookup.
+ *
+ * The per-instance URL used to inject per-instance origins into
+ * `OPENCLAW_ALLOWED_ORIGINS` and (post-PR2) to route incoming requests by
+ * `Host` is built from two env-configurable pieces:
+ *
+ *   KILOCLAW_INSTANCE_HOST_SUFFIX  default ".kiloclaw.ai"
+ *   KILOCLAW_INSTANCE_URL_SCHEME   default "https"
+ *
+ * Dev parity: set the suffix to `.kiloclaw.localhost:8795` and the scheme to
+ * `http` and the worker will both inject `http://<label>.kiloclaw.localhost:8795`
+ * into the container's origin allowlist and route requests matching that
+ * host to the owning DO. `.kiloclaw.localhost` auto-resolves to 127.0.0.1 on
+ * modern OSes + browsers per RFC 6761, so no `/etc/hosts` edit is required.
+ */
+
+import { isInstanceKeyedSandboxId } from './instance-id';
+
+/** RFC 1035 max label length. */
+export const MAX_HOSTNAME_LABEL_LENGTH = 63;
+
+/** Narrow view of the env bindings consumed by `instanceUrl` / `parseInstanceHost`. */
+export type HostSuffixEnv = {
+  KILOCLAW_INSTANCE_HOST_SUFFIX?: string;
+  KILOCLAW_INSTANCE_URL_SCHEME?: string;
+};
+
+/**
+ * No silent fallback: a misconfigured worker should fail loudly rather than
+ * inject `.kiloclaw.ai` / `https` into machine origins that were supposed to
+ * use a preview-specific or dev suffix. The canonical production values live
+ * in `services/kiloclaw/wrangler.jsonc` under `vars`, so this only throws
+ * when the var was explicitly cleared (unit test fixtures, malformed
+ * preview config, etc.). `validateRequiredEnv` on the catch-all middleware
+ * chain rejects requests with a 503 before this path is reached in a
+ * normal request flow.
+ */
+function requireEnv(env: HostSuffixEnv, key: keyof HostSuffixEnv): string {
+  const value = env[key];
+  if (typeof value !== 'string' || value.length === 0) {
+    throw new Error(`${key} is not set; refuse to fall back to a default host suffix/scheme`);
+  }
+  return value;
+}
+
+function hostSuffix(env: HostSuffixEnv): string {
+  return requireEnv(env, 'KILOCLAW_INSTANCE_HOST_SUFFIX');
+}
+
+function urlScheme(env: HostSuffixEnv): string {
+  return requireEnv(env, 'KILOCLAW_INSTANCE_URL_SCHEME');
+}
+
+const BASE32_HEX_ALPHABET = '0123456789abcdefghijklmnopqrstuv';
+const INSTANCE_KEYED_BODY_RE = /^[0-9a-f]{32}$/;
+
+const INSTANCE_LABEL_RE = /^i-([0-9a-f]{32})$/;
+const USER_LABEL_RE = /^u-([0-9a-v]+)$/;
+
+function bytesToBase64url(bytes: Uint8Array): string {
+  const binString = Array.from(bytes, b => String.fromCodePoint(b)).join('');
+  return btoa(binString).replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '');
+}
+
+function base64urlToBytes(encoded: string): Uint8Array | null {
+  try {
+    let b64 = encoded.replace(/-/g, '+').replace(/_/g, '/');
+    while (b64.length % 4 !== 0) {
+      b64 += '=';
+    }
+    const binString = atob(b64);
+    const bytes = Uint8Array.from(binString, c => c.codePointAt(0) ?? 0);
+    return bytesToBase64url(bytes) === encoded ? bytes : null;
+  } catch {
+    return null;
+  }
+}
+
+function bytesToBase32Hex(bytes: Uint8Array): string {
+  let output = '';
+  let buffer = 0;
+  let bits = 0;
+
+  for (const byte of bytes) {
+    buffer = (buffer << 8) | byte;
+    bits += 8;
+
+    while (bits >= 5) {
+      bits -= 5;
+      output += BASE32_HEX_ALPHABET[(buffer >> bits) & 31];
+    }
+  }
+
+  if (bits > 0) {
+    output += BASE32_HEX_ALPHABET[(buffer << (5 - bits)) & 31];
+  }
+
+  return output;
+}
+
+function base32HexToBytes(encoded: string): Uint8Array | null {
+  const bytes: number[] = [];
+  let buffer = 0;
+  let bits = 0;
+
+  for (const char of encoded) {
+    const value = BASE32_HEX_ALPHABET.indexOf(char);
+    if (value === -1) return null;
+
+    buffer = (buffer << 5) | value;
+    bits += 5;
+
+    while (bits >= 8) {
+      bits -= 8;
+      bytes.push((buffer >> bits) & 255);
+    }
+  }
+
+  const decoded = Uint8Array.from(bytes);
+  return bytesToBase32Hex(decoded) === encoded ? decoded : null;
+}
+
+/**
+ * Produce a DNS-safe hostname label for `<label>.kiloclaw.ai` from a
+ * sandboxId, or `null` if the sandboxId can't be represented as a safe
+ * label (e.g. pathological Unicode userId whose base64url encoding
+ * contains non-alnum chars, or a label that would exceed 63 chars).
+ *
+ * Callers should treat `null` as "no per-instance origin available for
+ * this sandbox" and fall back to the shared origin list.
+ */
+export function hostnameLabelFromSandboxId(sandboxId: string): string | null {
+  if (isInstanceKeyedSandboxId(sandboxId)) {
+    const body = sandboxId.slice(3);
+    if (!INSTANCE_KEYED_BODY_RE.test(body)) return null;
+    const label = `i-${body}`;
+    if (label.length > MAX_HOSTNAME_LABEL_LENGTH) return null;
+    return label;
+  }
+
+  const legacyUserIdBytes = base64urlToBytes(sandboxId);
+  if (!legacyUserIdBytes || legacyUserIdBytes.length === 0) return null;
+
+  const label = `u-${bytesToBase32Hex(legacyUserIdBytes)}`;
+  if (label.length > MAX_HOSTNAME_LABEL_LENGTH) return null;
+  return label;
+}
+
+/**
+ * Reverse of `hostnameLabelFromSandboxId`: parse a hostname label back
+ * into its sandboxId, returning `null` if the label doesn't match either
+ * scheme.
+ *
+ * Used by the host-based router in a follow-up PR to resolve
+ * `<label>.kiloclaw.ai` to the owning Instance DO.
+ */
+export function sandboxIdFromHostnameLabel(label: string): string | null {
+  const normalized = label.toLowerCase();
+  const instanceMatch = INSTANCE_LABEL_RE.exec(normalized);
+  if (instanceMatch) return `ki_${instanceMatch[1]}`;
+
+  const userMatch = USER_LABEL_RE.exec(normalized);
+  if (userMatch) {
+    const body = userMatch[1];
+    if (body.length + 2 > MAX_HOSTNAME_LABEL_LENGTH) return null;
+    const bytes = base32HexToBytes(body);
+    if (!bytes) return null;
+    return bytesToBase64url(bytes);
+  }
+
+  return null;
+}
+
+/**
+ * Build the per-instance URL (no path, no query) for the given label.
+ *
+ *   instanceUrl('i-abc', { KILOCLAW_INSTANCE_HOST_SUFFIX: '.kiloclaw.ai' })
+ *     => 'https://i-abc.kiloclaw.ai'
+ *   instanceUrl('i-abc', {
+ *     KILOCLAW_INSTANCE_HOST_SUFFIX: '.kiloclaw.localhost:8795',
+ *     KILOCLAW_INSTANCE_URL_SCHEME: 'http',
+ *   })
+ *     => 'http://i-abc.kiloclaw.localhost:8795'
+ *
+ * Used by the per-instance origin injector in `gateway/env.ts` and by any
+ * code that needs to mint the canonical user-facing host for an instance.
+ */
+export function instanceUrl(label: string, env: HostSuffixEnv): string {
+  return `${urlScheme(env)}://${label}${hostSuffix(env)}`;
+}
+
+/**
+ * Does the given host fall within the per-instance virtual-host space?
+ * True for anything ending in the configured suffix, including malformed
+ * cases (bare suffix, multi-label, unparseable label). Callers use this
+ * to decide whether the request should be handled by the host-based
+ * branch (which may still return 404) or fall through to cookie-based
+ * routing. Case-insensitive.
+ */
+export function hostMatchesInstanceSuffix(host: string, env: HostSuffixEnv): boolean {
+  return host.toLowerCase().endsWith(hostSuffix(env).toLowerCase());
+}
+
+/**
+ * Extract the hostname label from an incoming `Host` header if the host
+ * matches the configured instance-host suffix. Returns `null` if:
+ *
+ *   - the host doesn't end with the configured suffix
+ *   - the portion preceding the suffix is empty (e.g. ".kiloclaw.ai")
+ *   - the portion preceding the suffix contains a dot, i.e. multi-label
+ *     subdomain like `foo.bar.kiloclaw.ai`
+ *
+ * The suffix can legitimately contain a port in dev (`.kiloclaw.localhost:8795`),
+ * so we use raw suffix comparison rather than DNS-only parsing. The input
+ * host should be the full value of the `Host` header / `URL.host`, including
+ * any `:port` component.
+ *
+ * Case-insensitive: DNS is case-insensitive and CDNs/proxies may rewrite
+ * case. The returned label is lowercased so callers can run it through
+ * `sandboxIdFromHostnameLabel` (which also lowercases, but doing it here
+ * makes the behaviour explicit).
+ */
+export function parseInstanceHost(host: string, env: HostSuffixEnv): string | null {
+  const suffix = hostSuffix(env).toLowerCase();
+  const normalized = host.toLowerCase();
+  if (!normalized.endsWith(suffix)) return null;
+  const label = normalized.slice(0, -suffix.length);
+  if (label.length === 0) return null;
+  if (label.includes('.')) return null;
+  return label;
+}
diff --git a/packages/worker-utils/src/sandbox-id.ts b/packages/worker-utils/src/sandbox-id.ts
new file mode 100644
index 0000000000..83986162df
--- /dev/null
+++ b/packages/worker-utils/src/sandbox-id.ts
@@ -0,0 +1,50 @@
+/**
+ * Reversible base64url encoding of userId into sandboxId.
+ *
+ * NOT the cloud-agent-next SHA-256 pattern -- we need to recover userId
+ * from sandboxId in lifecycle hooks without a DB lookup.
+ *
+ * Uses TextEncoder/TextDecoder so non-Latin1 userIds (e.g. Unicode from
+ * some IdPs) don't throw at runtime. ASCII userIds encode identically
+ * to the old btoa() approach.
+ *
+ * No prefix -- the full 63-char sandboxId limit is available.
+ */
+
+const MAX_SANDBOX_ID_LENGTH = 63;
+
+function bytesToBase64url(bytes: Uint8Array): string {
+  const binString = Array.from(bytes, b => String.fromCodePoint(b)).join('');
+  return btoa(binString).replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '');
+}
+
+function base64urlToBytes(encoded: string): Uint8Array {
+  let b64 = encoded.replace(/-/g, '+').replace(/_/g, '/');
+  while (b64.length % 4 !== 0) {
+    b64 += '=';
+  }
+  const binString = atob(b64);
+  return Uint8Array.from(binString, c => c.codePointAt(0) ?? 0);
+}
+
+export function sandboxIdFromUserId(userId: string): string {
+  const bytes = new TextEncoder().encode(userId);
+  const encoded = bytesToBase64url(bytes);
+  if (encoded.length > MAX_SANDBOX_ID_LENGTH) {
+    throw new Error(
+      `userId too long: encoded sandboxId would be ${encoded.length} chars (max ${MAX_SANDBOX_ID_LENGTH})`
+    );
+  }
+  return encoded;
+}
+
+export function userIdFromSandboxId(sandboxId: string): string {
+  const bytes = base64urlToBytes(sandboxId);
+  return new TextDecoder('utf-8', { fatal: false, ignoreBOM: true }).decode(bytes);
+}
+
+// ─── Instance-scoped identity ───────────────────────────────────────
+// Canonical implementation lives in ./instance-id; re-exported here for
+// convenience so callers get both shapes from one module.
+
+export { isValidInstanceId, sandboxIdFromInstanceId } from './instance-id';
diff --git a/services/kiloclaw/src/auth/hostname-label.ts b/services/kiloclaw/src/auth/hostname-label.ts
index e6750bb95f..7fd445a4c5 100644
--- a/services/kiloclaw/src/auth/hostname-label.ts
+++ b/services/kiloclaw/src/auth/hostname-label.ts
@@ -1,240 +1,19 @@
 /**
- * Hostname label <-> sandboxId translation for per-instance virtual hosting
- * on `*.kiloclaw.ai` (or a configured dev-suffix).
+ * Hostname label helpers.
  *
- * Two instance shapes map to two label prefixes:
- *
- *   instance-keyed sandboxId  "ki_{32hex}"       <->  "i-{32hex}"
- *   legacy sandboxId          base64url(userId)   <->  "u-{base32hex(userId)}"
- *
- * Prefix disambiguates the two cases without a database lookup.
- *
- * The per-instance URL used to inject per-instance origins into
- * `OPENCLAW_ALLOWED_ORIGINS` and (post-PR2) to route incoming requests by
- * `Host` is built from two env-configurable pieces:
- *
- *   KILOCLAW_INSTANCE_HOST_SUFFIX  default ".kiloclaw.ai"
- *   KILOCLAW_INSTANCE_URL_SCHEME   default "https"
- *
- * Dev parity: set the suffix to `.kiloclaw.localhost:8795` and the scheme to
- * `http` and the worker will both inject `http://<label>.kiloclaw.localhost:8795`
- * into the container's origin allowlist and route requests matching that
- * host to the owning DO. `.kiloclaw.localhost` auto-resolves to 127.0.0.1 on
- * modern OSes + browsers per RFC 6761, so no `/etc/hosts` edit is required.
- */
-
-import { isInstanceKeyedSandboxId } from '@kilocode/worker-utils/instance-id';
-
-/** RFC 1035 max label length. */
-export const MAX_HOSTNAME_LABEL_LENGTH = 63;
-
-/** Narrow view of the env bindings consumed by `instanceUrl` / `parseInstanceHost`. */
-export type HostSuffixEnv = {
-  KILOCLAW_INSTANCE_HOST_SUFFIX?: string;
-  KILOCLAW_INSTANCE_URL_SCHEME?: string;
-};
-
-/**
- * No silent fallback: a misconfigured worker should fail loudly rather than
- * inject `.kiloclaw.ai` / `https` into machine origins that were supposed to
- * use a preview-specific or dev suffix. The canonical production values live
- * in `services/kiloclaw/wrangler.jsonc` under `vars`, so this only throws
- * when the var was explicitly cleared (unit test fixtures, malformed
- * preview config, etc.). `validateRequiredEnv` on the catch-all middleware
- * chain rejects requests with a 503 before this path is reached in a
- * normal request flow.
- */
-function requireEnv(env: HostSuffixEnv, key: keyof HostSuffixEnv): string {
-  const value = env[key];
-  if (typeof value !== 'string' || value.length === 0) {
-    throw new Error(`${key} is not set; refuse to fall back to a default host suffix/scheme`);
-  }
-  return value;
-}
-
-function hostSuffix(env: HostSuffixEnv): string {
-  return requireEnv(env, 'KILOCLAW_INSTANCE_HOST_SUFFIX');
-}
-
-function urlScheme(env: HostSuffixEnv): string {
-  return requireEnv(env, 'KILOCLAW_INSTANCE_URL_SCHEME');
-}
-
-const BASE32_HEX_ALPHABET = '0123456789abcdefghijklmnopqrstuv';
-const INSTANCE_KEYED_BODY_RE = /^[0-9a-f]{32}$/;
-
-const INSTANCE_LABEL_RE = /^i-([0-9a-f]{32})$/;
-const USER_LABEL_RE = /^u-([0-9a-v]+)$/;
-
-function bytesToBase64url(bytes: Uint8Array): string {
-  const binString = Array.from(bytes, b => String.fromCodePoint(b)).join('');
-  return btoa(binString).replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '');
-}
-
-function base64urlToBytes(encoded: string): Uint8Array | null {
-  try {
-    let b64 = encoded.replace(/-/g, '+').replace(/_/g, '/');
-    while (b64.length % 4 !== 0) {
-      b64 += '=';
-    }
-    const binString = atob(b64);
-    const bytes = Uint8Array.from(binString, c => c.codePointAt(0) ?? 0);
-    return bytesToBase64url(bytes) === encoded ? bytes : null;
-  } catch {
-    return null;
-  }
-}
-
-function bytesToBase32Hex(bytes: Uint8Array): string {
-  let output = '';
-  let buffer = 0;
-  let bits = 0;
-
-  for (const byte of bytes) {
-    buffer = (buffer << 8) | byte;
-    bits += 8;
-
-    while (bits >= 5) {
-      bits -= 5;
-      output += BASE32_HEX_ALPHABET[(buffer >> bits) & 31];
-    }
-  }
-
-  if (bits > 0) {
-    output += BASE32_HEX_ALPHABET[(buffer << (5 - bits)) & 31];
-  }
-
-  return output;
-}
-
-function base32HexToBytes(encoded: string): Uint8Array | null {
-  const bytes: number[] = [];
-  let buffer = 0;
-  let bits = 0;
-
-  for (const char of encoded) {
-    const value = BASE32_HEX_ALPHABET.indexOf(char);
-    if (value === -1) return null;
-
-    buffer = (buffer << 5) | value;
-    bits += 5;
-
-    while (bits >= 8) {
-      bits -= 8;
-      bytes.push((buffer >> bits) & 255);
-    }
-  }
-
-  const decoded = Uint8Array.from(bytes);
-  return bytesToBase32Hex(decoded) === encoded ? decoded : null;
-}
-
-/**
- * Produce a DNS-safe hostname label for `<label>.kiloclaw.ai` from a
- * sandboxId, or `null` if the sandboxId can't be represented as a safe
- * label (e.g. pathological Unicode userId whose base64url encoding
- * contains non-alnum chars, or a label that would exceed 63 chars).
- *
- * Callers should treat `null` as "no per-instance origin available for
- * this sandbox" and fall back to the shared origin list.
- */
-export function hostnameLabelFromSandboxId(sandboxId: string): string | null {
-  if (isInstanceKeyedSandboxId(sandboxId)) {
-    const body = sandboxId.slice(3);
-    if (!INSTANCE_KEYED_BODY_RE.test(body)) return null;
-    const label = `i-${body}`;
-    if (label.length > MAX_HOSTNAME_LABEL_LENGTH) return null;
-    return label;
-  }
-
-  const legacyUserIdBytes = base64urlToBytes(sandboxId);
-  if (!legacyUserIdBytes || legacyUserIdBytes.length === 0) return null;
-
-  const label = `u-${bytesToBase32Hex(legacyUserIdBytes)}`;
-  if (label.length > MAX_HOSTNAME_LABEL_LENGTH) return null;
-  return label;
-}
-
-/**
- * Reverse of `hostnameLabelFromSandboxId`: parse a hostname label back
- * into its sandboxId, returning `null` if the label doesn't match either
- * scheme.
- *
- * Used by the host-based router in a follow-up PR to resolve
- * `<label>.kiloclaw.ai` to the owning Instance DO.
- */
-export function sandboxIdFromHostnameLabel(label: string): string | null {
-  const normalized = label.toLowerCase();
-  const instanceMatch = INSTANCE_LABEL_RE.exec(normalized);
-  if (instanceMatch) return `ki_${instanceMatch[1]}`;
-
-  const userMatch = USER_LABEL_RE.exec(normalized);
-  if (userMatch) {
-    const body = userMatch[1];
-    if (body.length + 2 > MAX_HOSTNAME_LABEL_LENGTH) return null;
-    const bytes = base32HexToBytes(body);
-    if (!bytes) return null;
-    return bytesToBase64url(bytes);
-  }
-
-  return null;
-}
-
-/**
- * Build the per-instance URL (no path, no query) for the given label.
- *
- *   instanceUrl('i-abc', { KILOCLAW_INSTANCE_HOST_SUFFIX: '.kiloclaw.ai' })
- *     => 'https://i-abc.kiloclaw.ai'
- *   instanceUrl('i-abc', {
- *     KILOCLAW_INSTANCE_HOST_SUFFIX: '.kiloclaw.localhost:8795',
- *     KILOCLAW_INSTANCE_URL_SCHEME: 'http',
- *   })
- *     => 'http://i-abc.kiloclaw.localhost:8795'
- *
- * Used by the per-instance origin injector in `gateway/env.ts` and by any
- * code that needs to mint the canonical user-facing host for an instance.
+ * Canonical implementation lives in `@kilocode/worker-utils/hostname-label`
+ * so it can be shared with `apps/web` (per-instance URL minting) without
+ * duplicating the label encoding. This module is a thin re-export shim
+ * kept in place so the many existing `./auth/hostname-label` imports in
+ * the worker don't have to migrate all at once.
  */
-export function instanceUrl(label: string, env: HostSuffixEnv): string {
-  return `${urlScheme(env)}://${label}${hostSuffix(env)}`;
-}
 
-/**
- * Does the given host fall within the per-instance virtual-host space?
- * True for anything ending in the configured suffix, including malformed
- * cases (bare suffix, multi-label, unparseable label). Callers use this
- * to decide whether the request should be handled by the host-based
- * branch (which may still return 404) or fall through to cookie-based
- * routing. Case-insensitive.
- */
-export function hostMatchesInstanceSuffix(host: string, env: HostSuffixEnv): boolean {
-  return host.toLowerCase().endsWith(hostSuffix(env).toLowerCase());
-}
-
-/**
- * Extract the hostname label from an incoming `Host` header if the host
- * matches the configured instance-host suffix. Returns `null` if:
- *
- *   - the host doesn't end with the configured suffix
- *   - the portion preceding the suffix is empty (e.g. ".kiloclaw.ai")
- *   - the portion preceding the suffix contains a dot, i.e. multi-label
- *     subdomain like `foo.bar.kiloclaw.ai`
- *
- * The suffix can legitimately contain a port in dev (`.kiloclaw.localhost:8795`),
- * so we use raw suffix comparison rather than DNS-only parsing. The input
- * host should be the full value of the `Host` header / `URL.host`, including
- * any `:port` component.
- *
- * Case-insensitive: DNS is case-insensitive and CDNs/proxies may rewrite
- * case. The returned label is lowercased so callers can run it through
- * `sandboxIdFromHostnameLabel` (which also lowercases, but doing it here
- * makes the behaviour explicit).
- */
-export function parseInstanceHost(host: string, env: HostSuffixEnv): string | null {
-  const suffix = hostSuffix(env).toLowerCase();
-  const normalized = host.toLowerCase();
-  if (!normalized.endsWith(suffix)) return null;
-  const label = normalized.slice(0, -suffix.length);
-  if (label.length === 0) return null;
-  if (label.includes('.')) return null;
-  return label;
-}
+export {
+  MAX_HOSTNAME_LABEL_LENGTH,
+  hostnameLabelFromSandboxId,
+  sandboxIdFromHostnameLabel,
+  instanceUrl,
+  hostMatchesInstanceSuffix,
+  parseInstanceHost,
+} from '@kilocode/worker-utils/hostname-label';
+export type { HostSuffixEnv } from '@kilocode/worker-utils/hostname-label';
diff --git a/services/kiloclaw/src/auth/sandbox-id.ts b/services/kiloclaw/src/auth/sandbox-id.ts
index 434c8c665c..511362596b 100644
--- a/services/kiloclaw/src/auth/sandbox-id.ts
+++ b/services/kiloclaw/src/auth/sandbox-id.ts
@@ -1,50 +1,16 @@
 /**
- * Reversible base64url encoding of userId into sandboxId.
+ * SandboxId encoding helpers.
  *
- * NOT the cloud-agent-next SHA-256 pattern -- we need to recover userId
- * from sandboxId in lifecycle hooks without a DB lookup.
- *
- * Uses TextEncoder/TextDecoder so non-Latin1 userIds (e.g. Unicode from
- * some IdPs) don't throw at runtime. ASCII userIds encode identically
- * to the old btoa() approach.
- *
- * No prefix -- the full 63-char sandboxId limit is available.
+ * Canonical implementation lives in `@kilocode/worker-utils/sandbox-id`
+ * so it can be shared with `apps/web` (per-instance URL minting) without
+ * duplicating the base64url encoding. This module is a thin re-export
+ * shim kept in place so the many existing `./auth/sandbox-id` imports in
+ * the worker don't have to migrate all at once.
  */
 
-const MAX_SANDBOX_ID_LENGTH = 63;
-
-function bytesToBase64url(bytes: Uint8Array): string {
-  const binString = Array.from(bytes, b => String.fromCodePoint(b)).join('');
-  return btoa(binString).replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '');
-}
-
-function base64urlToBytes(encoded: string): Uint8Array {
-  let b64 = encoded.replace(/-/g, '+').replace(/_/g, '/');
-  while (b64.length % 4 !== 0) {
-    b64 += '=';
-  }
-  const binString = atob(b64);
-  return Uint8Array.from(binString, c => c.codePointAt(0) ?? 0);
-}
-
-export function sandboxIdFromUserId(userId: string): string {
-  const bytes = new TextEncoder().encode(userId);
-  const encoded = bytesToBase64url(bytes);
-  if (encoded.length > MAX_SANDBOX_ID_LENGTH) {
-    throw new Error(
-      `userId too long: encoded sandboxId would be ${encoded.length} chars (max ${MAX_SANDBOX_ID_LENGTH})`
-    );
-  }
-  return encoded;
-}
-
-export function userIdFromSandboxId(sandboxId: string): string {
-  const bytes = base64urlToBytes(sandboxId);
-  return new TextDecoder('utf-8', { fatal: false, ignoreBOM: true }).decode(bytes);
-}
-
-// ─── Instance-scoped identity ───────────────────────────────────────
-// Canonical implementation lives in @kilocode/worker-utils/instance-id;
-// re-exported here so existing imports within the worker package continue to work.
-
-export { isValidInstanceId, sandboxIdFromInstanceId } from '@kilocode/worker-utils/instance-id';
+export {
+  sandboxIdFromUserId,
+  userIdFromSandboxId,
+  isValidInstanceId,
+  sandboxIdFromInstanceId,
+} from '@kilocode/worker-utils/sandbox-id';
diff --git a/services/kiloclaw/src/index.test.ts b/services/kiloclaw/src/index.test.ts
index d8655c0467..734e8a790d 100644
--- a/services/kiloclaw/src/index.test.ts
+++ b/services/kiloclaw/src/index.test.ts
@@ -826,6 +826,50 @@ describe('host-based routing', () => {
     expect(response.status).toBe(404);
   });
 
+  it('skips host-based routing for reserved labels (e.g. claw) and falls through', async () => {
+    // `claw` is reserved for controller check-in + platform traffic that's
+    // registered before the catch-all. A request hitting the catch-all on
+    // `claw.kiloclaw.ai` means no earlier route matched — we want to fall
+    // through to cookie/default routing rather than 404 with "Instance not
+    // found" (the host-branch's response for unparseable labels), which
+    // would be a misleading error for a reserved operational hostname.
+    const instanceStub = {
+      getStatus: vi.fn(),
+    };
+    const registryStub = {
+      // Empty registry → default-personal path resolves no instance,
+      // responds with "Instance not provisioned". Distinct from the
+      // host-branch's "Instance not found".
+      listInstances: vi.fn().mockResolvedValue([]),
+    };
+    const response = await app.fetch(
+      new Request('https://claw.kiloclaw.ai/some-unhandled-path'),
+      {
+        ...baseEnv(),
+        KILOCLAW_INSTANCE: {
+          idFromName: vi.fn().mockReturnValue('instance-id'),
+          get: vi.fn().mockReturnValue(instanceStub),
+        },
+        KILOCLAW_REGISTRY: {
+          idFromName: vi.fn().mockReturnValue('registry-id'),
+          get: vi.fn().mockReturnValue(registryStub),
+        },
+      } as never,
+      { waitUntil: vi.fn() } as never
+    );
+
+    expect(response.status).toBe(404);
+    // Host branch would have replied `{ error: 'Instance not found' }`;
+    // the default branch replies `{ error: 'Instance not provisioned', ... }`.
+    // The latter body proves the reserved-label short-circuit kicked in.
+    await expect(response.json()).resolves.toMatchObject({
+      error: 'Instance not provisioned',
+    });
+    // Host branch would have called the Instance DO's getStatus for the
+    // `claw` label. It must not.
+    expect(instanceStub.getStatus).not.toHaveBeenCalled();
+  });
+
   it('returns 404 when the DO has no userId (instance never provisioned)', async () => {
     const instanceStub = {
       getStatus: vi.fn().mockResolvedValue({
diff --git a/services/kiloclaw/src/index.ts b/services/kiloclaw/src/index.ts
index 1b43824627..8e80bbaa91 100644
--- a/services/kiloclaw/src/index.ts
+++ b/services/kiloclaw/src/index.ts
@@ -159,44 +159,61 @@ function routingTargetUrl(target: ProviderRoutingTarget, pathname: string, searc
 /**
  * Forward an HTTP or WebSocket request through to a provider-routed target.
  *
- * Shared by the host-based branch of the catch-all proxy. The existing
- * cookie-based branch and the `/i/:instanceId/*` route predate this helper
- * and inline the same logic — they can be consolidated in a follow-up.
+ * Shared by all four catch-all proxy branches (`/i/:instanceId/*`, host-based,
+ * cookie-routed, and default personal). `logTag` is prepended to console logs
+ * so failing requests can be traced back to their originating branch.
  *
- * `logTag` is prepended to console logs so failing requests can be traced
- * back to their originating branch.
+ * Optional `unreachableHint` / `startingUpHint` are attached to the 503 JSON
+ * bodies the helper emits when the upstream fetch fails or the container is
+ * still booting. Only the default-personal branch surfaces hints today (tests
+ * assert the specific strings); branches that prefer the bare error
+ * (`{ "error": "Instance not reachable" }`) just omit them.
  */
 async function proxyThroughTarget(opts: {
   request: Request;
   targetUrl: string;
   forwardHeaders: Headers;
   logTag: string;
+  unreachableHint?: string;
+  startingUpHint?: string;
 }): Promise<Response> {
-  const { request, targetUrl, forwardHeaders, logTag } = opts;
+  const { request, targetUrl, forwardHeaders, logTag, unreachableHint, startingUpHint } = opts;
   const isWebSocketRequest = request.headers.get('Upgrade')?.toLowerCase() === 'websocket';
 
+  const unreachableBody: Record<string, string> = { error: 'Instance not reachable' };
+  if (unreachableHint) unreachableBody.hint = unreachableHint;
+  const startingUpBody: Record<string, string> = { error: 'Instance is starting up' };
+  if (startingUpHint) startingUpBody.hint = startingUpHint;
+
   if (isWebSocketRequest) {
     let containerResponse: Response;
     try {
       containerResponse = await fetch(targetUrl, { headers: forwardHeaders });
     } catch (err) {
       console.error(`${logTag} WS fetch failed:`, err);
-      return Response.json(
-        { error: 'Instance not reachable' },
-        { status: 503, headers: { 'Retry-After': '5' } }
-      );
+      return Response.json(unreachableBody, {
+        status: 503,
+        headers: { 'Retry-After': '5' },
+      });
     }
 
     if (containerResponse.status === 502) {
-      return Response.json(
-        { error: 'Instance is starting up' },
-        { status: 503, headers: { 'Retry-After': '5' } }
-      );
+      return Response.json(startingUpBody, {
+        status: 503,
+        headers: { 'Retry-After': '5' },
+      });
     }
 
     const containerWs = containerResponse.webSocket;
     if (!containerWs) {
-      return containerResponse;
+      // Upstream returned a non-upgrade response to a WebSocket request.
+      // Normalize to 502 JSON rather than leaking the raw upstream body —
+      // this path is only hit when the container is in a bad state
+      // (gateway crash, proxy misconfig) and the raw response may contain
+      // provider/controller error details we don't want to surface to
+      // the Control UI.
+      console.warn(`${logTag} upstream did not upgrade (status ${containerResponse.status})`);
+      return Response.json({ error: 'WebSocket upgrade failed' }, { status: 502 });
     }
 
     const [clientWs, serverWs] = Object.values(new WebSocketPair());
@@ -279,10 +296,10 @@ async function proxyThroughTarget(opts: {
     return httpResponse;
   } catch (err) {
     console.error(`${logTag} HTTP fetch failed:`, err);
-    return Response.json(
-      { error: 'Instance not reachable' },
-      { status: 503, headers: { 'Retry-After': '5' } }
-    );
+    return Response.json(unreachableBody, {
+      status: 503,
+      headers: { 'Retry-After': '5' },
+    });
   }
 }
 
@@ -507,117 +524,12 @@ app.all('/i/:instanceId/*', async c => {
     status.runtimeId
   );
 
-  const isWebSocketRequest = c.req.raw.headers.get('Upgrade')?.toLowerCase() === 'websocket';
-
-  if (isWebSocketRequest) {
-    let containerResponse: Response;
-    try {
-      containerResponse = await fetch(targetUrl, { headers: forwardHeaders });
-    } catch (err) {
-      console.error('[PROXY /i] Fly Proxy fetch failed:', err);
-      return c.json(
-        { error: 'Instance not reachable' },
-        { status: 503, headers: { 'Retry-After': '5' } }
-      );
-    }
-
-    if (containerResponse.status === 502) {
-      return c.json(
-        { error: 'Instance is starting up' },
-        { status: 503, headers: { 'Retry-After': '5' } }
-      );
-    }
-
-    const containerWs = containerResponse.webSocket;
-    if (!containerWs) {
-      return containerResponse;
-    }
-
-    const [clientWs, serverWs] = Object.values(new WebSocketPair());
-    serverWs.accept();
-    containerWs.accept();
-
-    let droppedToContainer = 0;
-    let droppedToClient = 0;
-
-    serverWs.addEventListener('message', event => {
-      if (containerWs.readyState === WebSocket.OPEN) {
-        containerWs.send(event.data as string | ArrayBuffer);
-      } else {
-        droppedToContainer++;
-        if (droppedToContainer === 1) {
-          console.warn(
-            '[WS /i] First dropped client->container message (readyState:',
-            containerWs.readyState,
-            ')'
-          );
-        }
-      }
-    });
-    containerWs.addEventListener('message', event => {
-      const data = transformWsMessage(event.data as string | ArrayBuffer);
-      if (serverWs.readyState === WebSocket.OPEN) {
-        serverWs.send(data);
-      } else {
-        droppedToClient++;
-        if (droppedToClient === 1) {
-          console.warn(
-            '[WS /i] First dropped container->client message (readyState:',
-            serverWs.readyState,
-            ')'
-          );
-        }
-      }
-    });
-
-    const logDropSummary = () => {
-      const totalDropped = droppedToClient + droppedToContainer;
-      if (totalDropped > 0) {
-        console.warn(
-          '[WS /i] Connection closed with',
-          totalDropped,
-          'dropped messages (toClient:',
-          droppedToClient,
-          'toContainer:',
-          droppedToContainer,
-          ')'
-        );
-      }
-    };
-
-    serverWs.addEventListener('close', event => {
-      logDropSummary();
-      safeClose(containerWs, event.code, event.reason);
-    });
-    containerWs.addEventListener('close', event => {
-      logDropSummary();
-      safeClose(serverWs, event.code, sanitizeCloseReason(event.reason));
-    });
-    serverWs.addEventListener('error', () => safeClose(containerWs, 1011, 'Client error'));
-    containerWs.addEventListener('error', () => safeClose(serverWs, 1011, 'Container error'));
-
-    return new Response(null, { status: 101, webSocket: clientWs });
-  }
-
-  // HTTP proxy
-  const requestBody = c.req.raw.body ? await c.req.raw.arrayBuffer() : null;
-  try {
-    const httpResponse = await fetch(targetUrl, {
-      method: c.req.raw.method,
-      headers: forwardHeaders,
-      body: requestBody,
-    });
-    if (httpResponse.status === 502) {
-      return startingUpPage();
-    }
-    return httpResponse;
-  } catch (err) {
-    console.error('[PROXY /i] HTTP fetch failed:', err);
-    return c.json(
-      { error: 'Instance not reachable' },
-      { status: 503, headers: { 'Retry-After': '5' } }
-    );
-  }
+  return proxyThroughTarget({
+    request: c.req.raw,
+    targetUrl,
+    forwardHeaders,
+    logTag: '[PROXY /i]',
+  });
 });
 
 // =============================================================================
@@ -712,6 +624,20 @@ async function resolveInstance(c: Context<AppEnv>): Promise<{
   };
 }
 
+/**
+ * Reserved hostname labels under the instance-host suffix that are NOT
+ * per-instance virtual hosts. Requests to these land on the worker via
+ * the `*.kiloclaw.ai/*` wildcard route but must be served by
+ * earlier-registered routes (controller check-in, future platform
+ * endpoints) rather than the host-based proxy branch.
+ *
+ * Keeping this set small and explicit prevents accidental routing: a
+ * request to `claw.kiloclaw.ai/someuserpath` will fall through the
+ * host-based branch to cookie/default routing instead of 404ing with an
+ * "instance not found" that's actually a configuration misunderstanding.
+ */
+const RESERVED_INSTANCE_HOST_LABELS = new Set<string>(['claw']);
+
 /**
  * Resolve the DO key that a host-routed request should proxy to.
  *
@@ -761,6 +687,15 @@ async function handleHostBasedRoute(c: Context<AppEnv>): Promise<Response | null
     return c.json({ error: 'Instance not found' }, 404);
   }
 
+  // Reserved labels (e.g. `claw` for controller check-in, platform health
+  // probes) are served by earlier-registered routes. If we've reached the
+  // catch-all on a reserved label the path wasn't a controller/platform
+  // route — return null so the cookie/default branches handle it rather
+  // than 404ing with a misleading "instance not found".
+  if (RESERVED_INSTANCE_HOST_LABELS.has(label)) {
+    return null;
+  }
+
   const userId = c.get('userId');
   if (!userId) {
     return c.json({ error: 'Authentication required' }, 401);
@@ -977,117 +912,12 @@ app.all('*', async c => {
             providerHeaders: routingTarget.headers,
           });
 
-          const isWebSocketRequest = request.headers.get('Upgrade')?.toLowerCase() === 'websocket';
-
-          if (isWebSocketRequest) {
-            let containerResponse: Response;
-            try {
-              containerResponse = await fetch(targetUrl, { headers: forwardHeaders });
-            } catch (err) {
-              console.error('[PROXY] Cookie-routed WS fetch failed:', err);
-              return c.json(
-                { error: 'Instance not reachable' },
-                { status: 503, headers: { 'Retry-After': '5' } }
-              );
-            }
-
-            if (containerResponse.status === 502) {
-              return c.json(
-                { error: 'Instance is starting up' },
-                { status: 503, headers: { 'Retry-After': '5' } }
-              );
-            }
-
-            const containerWs = containerResponse.webSocket;
-            if (!containerWs) {
-              return c.json({ error: 'WebSocket upgrade failed' }, 502);
-            }
-            containerWs.accept();
-            const [clientWs, serverWs] = Object.values(new WebSocketPair());
-            serverWs.accept();
-
-            let cookieDroppedToContainer = 0;
-            let cookieDroppedToClient = 0;
-
-            serverWs.addEventListener('message', event => {
-              if (containerWs.readyState === WebSocket.OPEN) {
-                containerWs.send(event.data as string | ArrayBuffer);
-              } else {
-                cookieDroppedToContainer++;
-                if (cookieDroppedToContainer === 1) {
-                  console.warn(
-                    '[WS cookie] First dropped client->container message (readyState:',
-                    containerWs.readyState,
-                    ')'
-                  );
-                }
-              }
-            });
-            containerWs.addEventListener('message', event => {
-              const data = transformWsMessage(event.data as string | ArrayBuffer);
-              if (serverWs.readyState === WebSocket.OPEN) {
-                serverWs.send(data);
-              } else {
-                cookieDroppedToClient++;
-                if (cookieDroppedToClient === 1) {
-                  console.warn(
-                    '[WS cookie] First dropped container->client message (readyState:',
-                    serverWs.readyState,
-                    ')'
-                  );
-                }
-              }
-            });
-
-            const logCookieDropSummary = () => {
-              const totalDropped = cookieDroppedToClient + cookieDroppedToContainer;
-              if (totalDropped > 0) {
-                console.warn(
-                  '[WS cookie] Connection closed with',
-                  totalDropped,
-                  'dropped messages (toClient:',
-                  cookieDroppedToClient,
-                  'toContainer:',
-                  cookieDroppedToContainer,
-                  ')'
-                );
-              }
-            };
-
-            serverWs.addEventListener('close', event => {
-              logCookieDropSummary();
-              safeClose(containerWs, event.code, event.reason);
-            });
-            containerWs.addEventListener('close', event => {
-              logCookieDropSummary();
-              safeClose(serverWs, event.code, sanitizeCloseReason(event.reason));
-            });
-            serverWs.addEventListener('error', () => safeClose(containerWs, 1011, 'Client error'));
-            containerWs.addEventListener('error', () =>
-              safeClose(serverWs, 1011, 'Container error')
-            );
-            return new Response(null, { status: 101, webSocket: clientWs });
-          }
-
-          // HTTP proxy
-          const requestBody = request.body ? await request.arrayBuffer() : null;
-          try {
-            const httpResponse = await fetch(targetUrl, {
-              method: request.method,
-              headers: forwardHeaders,
-              body: requestBody,
-            });
-            if (httpResponse.status === 502) {
-              return startingUpPage();
-            }
-            return httpResponse;
-          } catch (err) {
-            console.error('[PROXY] Cookie-routed HTTP fetch failed:', err);
-            return c.json(
-              { error: 'Instance not reachable' },
-              { status: 503, headers: { 'Retry-After': '5' } }
-            );
-          }
+          return proxyThroughTarget({
+            request,
+            targetUrl,
+            forwardHeaders,
+            logTag: '[PROXY cookie]',
+          });
         }
       }
     }
@@ -1155,8 +985,6 @@ app.all('*', async c => {
 
   console.log('[PROXY] Handling request:', url.pathname, 'runtime:', runtimeId);
 
-  const isWebSocketRequest = request.headers.get('Upgrade')?.toLowerCase() === 'websocket';
-
   if (!c.env.GATEWAY_TOKEN_SECRET) {
     console.error('[CONFIG] Missing required environment variables: GATEWAY_TOKEN_SECRET');
     return c.json(
@@ -1176,157 +1004,14 @@ app.all('*', async c => {
     providerHeaders: routingTarget.headers,
   });
 
-  // WebSocket proxy
-  if (isWebSocketRequest) {
-    console.log('[WS] Proxying WebSocket connection to OpenClaw via Fly Proxy');
-
-    let containerResponse: Response;
-    try {
-      containerResponse = await fetch(targetUrl, {
-        headers: forwardHeaders,
-      });
-    } catch (err) {
-      console.error('[WS] Fly Proxy fetch failed:', err);
-      return c.json(
-        {
-          error: 'Instance not reachable',
-          hint: 'Your instance may not be running. Start it from the dashboard.',
-        },
-        { status: 503, headers: { 'Retry-After': '5' } }
-      );
-    }
-    console.log('[WS] Fly Proxy response status:', containerResponse.status);
-
-    // Gateway not ready yet — return a clear JSON error for WebSocket clients
-    if (containerResponse.status === 502) {
-      return c.json(
-        {
-          error: 'Instance is starting up',
-          hint: 'The gateway process is still initializing. Please retry shortly.',
-        },
-        { status: 503, headers: { 'Retry-After': '5' } }
-      );
-    }
-
-    const containerWs = containerResponse.webSocket;
-    if (!containerWs) {
-      console.error('[WS] No WebSocket in response - returning direct response');
-      return containerResponse;
-    }
-
-    const [clientWs, serverWs] = Object.values(new WebSocketPair());
-
-    serverWs.accept();
-    containerWs.accept();
-
-    let catchAllDroppedToContainer = 0;
-    let catchAllDroppedToClient = 0;
-
-    // Client -> Container relay
-    serverWs.addEventListener('message', event => {
-      if (containerWs.readyState === WebSocket.OPEN) {
-        containerWs.send(event.data as string | ArrayBuffer);
-      } else {
-        catchAllDroppedToContainer++;
-        if (catchAllDroppedToContainer === 1) {
-          console.warn(
-            '[WS] First dropped client->container message (readyState:',
-            containerWs.readyState,
-            ')'
-          );
-        }
-      }
-    });
-
-    // Container -> Client relay with error transformation
-    containerWs.addEventListener('message', event => {
-      const data = transformWsMessage(event.data as string | ArrayBuffer);
-      if (serverWs.readyState === WebSocket.OPEN) {
-        serverWs.send(data);
-      } else {
-        catchAllDroppedToClient++;
-        if (catchAllDroppedToClient === 1) {
-          console.warn(
-            '[WS] First dropped container->client message (readyState:',
-            serverWs.readyState,
-            ')'
-          );
-        }
-      }
-    });
-
-    const logCatchAllDropSummary = () => {
-      const totalDropped = catchAllDroppedToClient + catchAllDroppedToContainer;
-      if (totalDropped > 0) {
-        console.warn(
-          '[WS] Connection closed with',
-          totalDropped,
-          'dropped messages (toClient:',
-          catchAllDroppedToClient,
-          'toContainer:',
-          catchAllDroppedToContainer,
-          ')'
-        );
-      }
-    };
-
-    // Close relay
-    serverWs.addEventListener('close', event => {
-      logCatchAllDropSummary();
-      safeClose(containerWs, event.code, event.reason);
-    });
-
-    containerWs.addEventListener('close', event => {
-      logCatchAllDropSummary();
-      safeClose(serverWs, event.code, sanitizeCloseReason(event.reason));
-    });
-
-    // Error relay
-    serverWs.addEventListener('error', event => {
-      console.error('[WS] Client error:', event);
-      safeClose(containerWs, 1011, 'Client error');
-    });
-
-    containerWs.addEventListener('error', event => {
-      console.error('[WS] Container error:', event);
-      safeClose(serverWs, 1011, 'Container error');
-    });
-
-    return new Response(null, {
-      status: 101,
-      webSocket: clientWs,
-    });
-  }
-
-  // HTTP proxy
-  // Buffer body upfront so it can be replayed on crash-recovery retry (streams are one-shot).
-  const requestBody = request.body ? await request.arrayBuffer() : null;
-  console.log('[HTTP] Proxying:', url.pathname + url.search);
-  let httpResponse: Response;
-  try {
-    httpResponse = await fetch(targetUrl, {
-      method: request.method,
-      headers: forwardHeaders,
-      body: requestBody,
-    });
-  } catch (err) {
-    console.error('[HTTP] Fly Proxy fetch failed:', err);
-    return c.json(
-      {
-        error: 'Instance not reachable',
-        hint: 'Your instance may not be running. Start it from the dashboard.',
-      },
-      { status: 503, headers: { 'Retry-After': '5' } }
-    );
-  }
-  console.log('[HTTP] Response status:', httpResponse.status);
-
-  // Gateway not ready yet — show friendly "starting up" page instead of raw 502
-  if (httpResponse.status === 502) {
-    return startingUpPage();
-  }
-
-  return httpResponse;
+  return proxyThroughTarget({
+    request,
+    targetUrl,
+    forwardHeaders,
+    logTag: '[PROXY default]',
+    unreachableHint: 'Your instance may not be running. Start it from the dashboard.',
+    startingUpHint: 'The gateway process is still initializing. Please retry shortly.',
+  });
 });
 
 export default class extends WorkerEntrypoint<KiloClawEnv> {
diff --git a/services/kiloclaw/wrangler.jsonc b/services/kiloclaw/wrangler.jsonc
index fa388cb855..e0c85970e2 100644
--- a/services/kiloclaw/wrangler.jsonc
+++ b/services/kiloclaw/wrangler.jsonc
@@ -142,7 +142,15 @@
     // `buildEnvVars` in src/gateway/env.ts appends
     // `https://<instanceId>.kiloclaw.ai` per-instance at machine build time.
     "OPENCLAW_ALLOWED_ORIGINS": "https://claw.kilosessions.ai,https://kilo.ai,https://www.kilo.ai",
-    "KILOCLAW_CHECKIN_URL": "https://claw.kilosessions.ai/api/controller/checkin",
+    // Controller check-in URL baked into newly-provisioned / restarted
+    // machines. Points at a single canonical hostname under
+    // `kiloclaw.ai` so the legacy `claw.kilosessions.ai` custom domain
+    // can be retired once the fleet rolls over. Both hostnames resolve
+    // to the same worker, so in-flight machines on the old URL keep
+    // working through the transition. Apex is not routed, so we use a
+    // dedicated `claw` subdomain (covered by the `*.kiloclaw.ai/*`
+    // wildcard route).
+    "KILOCLAW_CHECKIN_URL": "https://claw.kiloclaw.ai/api/controller/checkin",
     // Per-instance virtual hosting. Three call sites share this suffix:
     //   1. `parseInstanceHost` (catch-all proxy, PR2) routes `<label>.kiloclaw.ai`
     //      requests by `Host` header.