Remove the shared default instance behind service hosts

A service host like github.emulators.dev used to be a stateful shared
instance: a well-known URL with world-readable state and a world-writable
control plane, which is exactly the polling target the unguessable
instance names were introduced to prevent. Service hosts are now control
plane only (manifest, quickstart, specs, coverage, connections, openapi,
and instance creation); provider routes return a 404 that points at
POST /_emulate/instances. Named instances, the path form, and the shared
MCP preset instances are unchanged. The console no longer pins service
hosts to a default instance and addresses instances via the apex path
form.

Author: RhysSullivan

README.md

@@ -159,7 +159,7 @@ github:
 All services are available on host-based routing when deployed: `github`, `gitlab`, `mcp`, `vercel`, `google`, `okta`, `microsoft`, `spotify`, `slack`, `apple`, `aws`, `resend`, `stripe`, `mongoatlas`, `clerk`, `x`, `workos`, `autumn`, and `posthog`. Each one supports three addressing forms:
 
 ```text
-https://github.emulators.dev                     # service host (no instance)
+https://github.emulators.dev                     # service host (control plane only)
 https://github.my-instance.emulators.dev         # instance host
 https://emulators.dev/github/my-instance         # local/path form
 ```
@@ -170,7 +170,7 @@ Create instances with `POST /_emulate/instances`: the server generates an ungues
 
 ### Useful without an instance
 
-The bare service host (for example `https://github.emulators.dev`) serves a service-level control plane so a human or agent can learn what the service is and connect without first creating an instance. It responds to `GET /_emulate`, `/_emulate/manifest`, `/_emulate/quickstart`, `/_emulate/specs`, `/_emulate/coverage`, `/_emulate/connections`, `/_emulate/openapi`, and `POST /_emulate/instances`.
+The bare service host (for example `https://github.emulators.dev`) serves a service-level control plane so a human or agent can learn what the service is and connect without first creating an instance. It responds to `GET /_emulate`, `/_emulate/manifest`, `/_emulate/quickstart`, `/_emulate/specs`, `/_emulate/coverage`, `/_emulate/connections`, `/_emulate/openapi`, and `POST /_emulate/instances`. There is no shared instance behind the service host: provider routes return a 404 pointing at instance creation, so all provider traffic happens on an instance of your own.
 
 A global catalog lists every hosted service from any host, including the apex:
 

apps/console/src/App.tsx

@@ -1,6 +1,6 @@
 import { useState } from "react";
 import { Link, Route, Routes } from "react-router-dom";
-import { DEFAULT_INSTANCE, hostRoute } from "./api";
+import { hostRoute } from "./api";
 import Home from "./views/Home";
 import Service from "./views/Service";
 
@@ -53,11 +53,7 @@ export default function App() {
           <Route
             path="/"
             element={
-              route.service ? (
-                <Service serviceOverride={route.service} instanceOverride={route.instance ?? DEFAULT_INSTANCE} />
-              ) : (
-                <Home />
-              )
+              route.service ? <Service serviceOverride={route.service} instanceOverride={route.instance} /> : <Home />
             }
           />
           <Route path="/:service" element={<Service />} />

apps/console/src/api.ts

@@ -7,10 +7,6 @@ export const ORIGIN = typeof window !== "undefined" ? window.location.origin : "
 
 const HOST_SUFFIX = "emulators.dev";
 
-// The service host (e.g. github.emulators.dev) is itself a default, stateful
-// instance. Named instances use the cert-safe path form on the apex.
-export const DEFAULT_INSTANCE = "default";
-
 const onEmulatorsHost = (): boolean => {
   if (typeof window === "undefined") return false;
   const h = window.location.hostname;
@@ -55,10 +51,10 @@ export const serviceHost = (service: string): string => {
 export const base = (service: string, instance: string): string => {
   if (typeof window === "undefined") return "";
   const route = hostRoute();
-  // On this service's own host, talk same-origin: the service host is the default
-  // instance, and a matching named-instance host serves itself.
-  if (route.service === service && (!route.instance || route.instance === instance)) return ORIGIN;
-  // Otherwise address via the cert-safe path form on the apex.
+  // A matching named-instance host serves itself same-origin. A bare service
+  // host does not: it is control plane only (no shared default instance), so
+  // instances are addressed via the cert-safe path form on the apex.
+  if (route.service === service && route.instance === instance) return ORIGIN;
   return `${apexOrigin()}/${service}/${encodeURIComponent(instance)}`;
 };
 

apps/web/app/docs/architecture/page.mdx

@@ -80,7 +80,7 @@ The core provides shared middleware:
 The `@emulators/cloudflare` package runs the same plugins on Cloudflare Workers with host-based routing. The `emulate-hosts` worker serves `emulators.dev/*` and `*.emulators.dev/*`:
 
 - The apex `emulators.dev` is the emulator catalog, a links-out landing built from `GET /_emulate/services`. It is not the docs site.
-- A service host such as `github.emulators.dev` serves a service-level control plane and is useful before any instance exists.
+- A service host such as `github.emulators.dev` serves a service-level control plane and is useful before any instance exists. It has no shared instance of its own; provider traffic requires a created instance.
 - An instance host such as `github.my-run.emulators.dev` (or the compatibility path form `emulators.dev/github/my-run`) serves one stateful instance.
 
 Each instance is backed by one Cloudflare Durable Object. The `EmulatorDurableObject` class is declared through a wrangler `migrations` entry (`new_classes`), and both the instance state and the request ledger are snapshotted to Durable Object storage so an instance survives eviction. Instances are created lazily through `POST /_emulate/instances`.

apps/web/app/docs/deployment/page.mdx

@@ -23,7 +23,7 @@ Hosted services are available on host-based routing. There are four address form
     <tr>
       <td>Service host</td>
       <td><code>https://github.emulators.dev</code></td>
-      <td>A single service, useful before you create an instance. Serves a service-level control plane</td>
+      <td>A single service, control plane only. Serves the service-level control plane and instance creation; provider routes require an instance</td>
     </tr>
     <tr>
       <td>Instance host</td>
@@ -70,7 +70,7 @@ curl -s https://emulators.dev/_emulate/services
 
 ## Service host control plane
 
-A bare service host such as `https://github.emulators.dev`, with no instance, serves a service-level control plane so it is useful before you create an instance:
+A bare service host such as `https://github.emulators.dev`, with no instance, serves a service-level control plane so it is useful before you create an instance. There is no shared instance behind it; provider routes return a 404 that points at instance creation:
 
 - `GET /_emulate`, `/_emulate/manifest`, `/_emulate/quickstart`, `/_emulate/specs`, `/_emulate/coverage`, `/_emulate/connections`, `/_emulate/openapi`
 - `POST /_emulate/instances` to create an instance and get its URLs

packages/@emulators/cloudflare/src/__tests__/worker.test.ts

@@ -102,56 +102,45 @@ describe("cloudflare worker routing", () => {
     expect(created.instance).toMatch(/^[0-9a-f]{24}$/);
   });
 
-  it("routes the service host to a default instance over the valid 1-label cert", async () => {
-    const seen: Array<{
-      idName: string;
-      url: string;
-      service: string | null;
-      instance: string | null;
-      baseUrl: string | null;
-    }> = [];
+  it("serves the service host as control plane only, with no shared default instance", async () => {
+    let doHits = 0;
     const env: Env = {
       EMULATE_HOST_SUFFIX: "emulators.dev",
       EMULATOR: {
         idFromName: (n) => n,
-        get: (id) => ({
-          async fetch(request) {
-            seen.push({
-              idName: String(id),
-              url: request.url,
-              service: request.headers.get("x-emulator-service"),
-              instance: request.headers.get("x-emulator-instance"),
-              baseUrl: request.headers.get("x-emulator-base-url"),
-            });
+        get: () => ({
+          async fetch() {
+            doHits++;
             return Response.json({ ok: true });
           },
         }),
       },
     };
 
-    // Provider API and /_emulate both resolve to the default instance.
-    await worker.fetch(
+    // The service-level control plane answers without any instance (or DO call).
+    const manifestRes = await worker.fetch(new Request("https://github.emulators.dev/_emulate/manifest"), env);
+    expect(manifestRes.status).toBe(200);
+    const manifest = (await manifestRes.json()) as { manifest: { id: string }; instance: unknown };
+    expect(manifest.manifest.id).toBe("github");
+    expect(manifest.instance).toBeNull();
+
+    // Provider routes have no shared instance behind the well-known host: they
+    // point at instance creation instead of serving world-readable state.
+    const provider = await worker.fetch(
       new Request("https://github.emulators.dev/user", { headers: { accept: "application/json" } }),
       env,
     );
-    await worker.fetch(new Request("https://github.emulators.dev/_emulate/manifest"), env);
+    expect(provider.status).toBe(404);
+    await expect(provider.json()).resolves.toMatchObject({
+      error: "instance_required",
+      createInstance: "https://github.emulators.dev/_emulate/instances",
+    });
 
-    expect(seen).toEqual([
-      {
-        idName: "github:default",
-        url: "https://github.emulators.dev/user",
-        service: "github",
-        instance: "default",
-        baseUrl: "https://github.emulators.dev",
-      },
-      {
-        idName: "github:default",
-        url: "https://github.emulators.dev/_emulate/manifest",
-        service: "github",
-        instance: "default",
-        baseUrl: "https://github.emulators.dev",
-      },
-    ]);
+    // Same for instance-scoped control-plane routes like /_emulate/state.
+    const state = await worker.fetch(new Request("https://github.emulators.dev/_emulate/state"), env);
+    expect(state.status).toBe(404);
+
+    expect(doHits).toBe(0);
   });
 
   it("serves the SPA to browser navigations but the no-JS landing to agents", async () => {
@@ -174,12 +163,23 @@ describe("cloudflare worker routing", () => {
       env,
     );
     expect(browser.headers.get("content-type")).toContain("text/html");
-    expect(doHits).toBe(0); // SPA served directly, no DO call
 
+    // Agent root gets the server-rendered service landing; agents asking for
+    // JSON get the service-level manifest. Neither touches a Durable Object.
     const agent = await worker.fetch(new Request("https://github.emulators.dev/", { headers: { accept: "*/*" } }), env);
     expect(agent.status).toBe(200);
-    expect(doHits).toBe(1); // agent root forwarded to the default instance's /_emulate landing
-    await expect(agent.json()).resolves.toMatchObject({ path: "/_emulate" });
+    expect(agent.headers.get("content-type")).toContain("text/html");
+    expect(await agent.text()).toContain("Create an instance");
+
+    const agentJson = await worker.fetch(
+      new Request("https://github.emulators.dev/", { headers: { accept: "application/json" } }),
+      env,
+    );
+    expect(agentJson.status).toBe(200);
+    const body = (await agentJson.json()) as { manifest: { id: string } };
+    expect(body.manifest.id).toBe("github");
+
+    expect(doHits).toBe(0);
   });
 
   it("lists the deployed service catalog from any host", async () => {

packages/@emulators/cloudflare/src/console-html.ts

@@ -1,4 +1,10 @@
-import { buildInstanceCreation, randomInstanceName, renderCatalogPage, servicesCatalog } from "@emulators/core";
+import {
+  buildInstanceCreation,
+  randomInstanceName,
+  renderCatalogPage,
+  serviceHostControlPlane,
+  servicesCatalog,
+} from "@emulators/core";
 import { EmulatorDurableObject } from "./durable-object.js";
 import { SERVICES } from "./services.js";
 import { SERVICE_ICONS } from "./icons.js";
@@ -37,9 +43,6 @@ export interface Env {
 }
 
 const DEFAULT_HOST_SUFFIX = "emulators.dev";
-// The service host (e.g. github.emulators.dev) IS a usable, stateful instance.
-// Named, isolated instances use the cert-safe path form emulators.dev/<svc>/<id>.
-const DEFAULT_INSTANCE = "default";
 // The instance segment selects the MCP surface's auth/scope preset:
 //  - oauth | bearer | query: how `/mcp` authenticates.
 //  - scope-discovery: oauth, but the protected-resource metadata stays silent on
@@ -86,7 +89,7 @@ async function forwardToDurableObject(
 }
 
 // Router:
-// - `<service>.<suffix>`            -> the service host == a default stateful instance.
+// - `<service>.<suffix>`            -> the service-level control plane (no shared instance).
 // - `<service>.<instance>.<suffix>` -> a named instance host (requires a 2-label cert).
 // - `/<service>/<instance>/...`     -> the cert-safe path form (named instances, local dev).
 // - apex / bare `/<service>`        -> the catalog (SPA for browsers, server-rendered for agents).
@@ -121,8 +124,11 @@ export default {
       });
     }
 
-    // SERVICE HOST: <service>.<suffix> with no instance label. The host itself is a
-    // default, stateful instance, served same-origin over the valid 1-label cert.
+    // SERVICE HOST: <service>.<suffix> with no instance label. Control plane
+    // only — there is deliberately NO shared default instance behind it. A
+    // well-known host with world-readable state and a world-writable control
+    // plane is exactly the polling target the unguessable instance names exist
+    // to prevent, so provider traffic requires an instance of your own.
     if (hostRoute?.service && !hostRoute.instance) {
       const service = hostRoute.service;
       const entry = SERVICES[service];
@@ -148,26 +154,45 @@ export default {
       if (!entry) return html(consoleHtml);
 
       // Root: browsers get the interactive console; agents/raw fetches get the
-      // server-rendered default-instance landing (no JS) or its JSON manifest.
+      // server-rendered service landing (no JS) or the service-level manifest.
       if (url.pathname === "/" || url.pathname === "") {
         if (isBrowserNavigation(request)) return html(consoleHtml);
-        return forwardToDurableObject(env, request, {
+        const landing = serviceHostControlPlane(wantsJson(request) ? "/_emulate/manifest" : "/_emulate", "GET", {
+          manifest: entry.manifest,
           service,
-          instance: DEFAULT_INSTANCE,
-          baseUrl: `${url.protocol}//${service}.${suffix}`,
-          innerPath: wantsJson(request) ? "/_emulate/manifest" : "/_emulate",
-          search: "",
+          origin: apexOrigin,
+          protocol: url.protocol,
+          hostSuffix: suffix,
+          ledgerPersistent: true,
         });
+        if (landing) return landing;
       }
 
-      // Everything else (provider API + /_emulate/*) → the default instance.
-      return forwardToDurableObject(env, request, {
+      // Service-level control plane (manifest, quickstart, specs, coverage,
+      // connections, openapi) — answerable without any instance.
+      const controlPlane = serviceHostControlPlane(url.pathname, request.method, {
+        manifest: entry.manifest,
         service,
-        instance: DEFAULT_INSTANCE,
-        baseUrl: `${url.protocol}//${service}.${suffix}`,
-        innerPath: url.pathname,
-        search: url.search,
+        origin: apexOrigin,
+        protocol: url.protocol,
+        hostSuffix: suffix,
+        ledgerPersistent: true,
       });
+      if (controlPlane) return controlPlane;
+
+      // Browsers exploring other paths still get the console SPA.
+      if (isBrowserNavigation(request)) return html(consoleHtml);
+
+      // Provider routes have no shared instance to serve: point the caller at
+      // instance creation instead.
+      return Response.json(
+        {
+          error: "instance_required",
+          message: `${service}.${suffix} is a service host with no shared instance. Create one with POST ${url.protocol}//${service}.${suffix}/_emulate/instances and use the returned providerBaseUrl.`,
+          createInstance: `${url.protocol}//${service}.${suffix}/_emulate/instances`,
+        },
+        { status: 404 },
+      );
     }
 
     // NAMED INSTANCE HOST: <service>.<instance>.<suffix> (needs a 2-label cert).

packages/@emulators/cloudflare/src/worker.ts

@@ -187,7 +187,7 @@ export function renderCatalogPage(
       <div class="s-card">
         <div class="section-heading">For agents</div>
         <p class="info-text">Machine-readable catalog: <a href="/_emulate/services">/_emulate/services</a></p>
-        <p class="info-text">Each service host serves <code>/_emulate/manifest</code>, <code>/_emulate/quickstart</code>, and <code>/_emulate/connections</code>, and the provider API directly against a default instance.</p>
+        <p class="info-text">Each service host serves <code>/_emulate/manifest</code>, <code>/_emulate/quickstart</code>, and <code>/_emulate/connections</code>, plus <code>POST /_emulate/instances</code> to create a private instance for provider traffic.</p>
       </div>
     `,
   );

packages/@emulators/core/src/service-host.ts

@@ -62,8 +62,8 @@ Global catalog:
   autumn, posthog, and mcp.
   Microsoft Graph includes OneDrive file content upload/download routes under
   /v1.0/me/drive and /v1.0/drives/:driveId.
-  Service host:    <service>.emulators.dev (useful without an instance; serves
-                   a service-level /_emulate control plane)
+  Service host:    <service>.emulators.dev (control plane only, no shared
+                   instance; create one via POST /_emulate/instances)
   Instance host:   <service>.<instance>.emulators.dev
   Local/path form: <origin>/<service>/<instance>