Deployment

Hosted emulators run on Cloudflare and are addressed by host. A human or agent can land on a service host, learn what the service is, create or select an instance, mint credentials, find base URLs, and inspect calls without any repository context. Provider traffic stays faithful to the real service, while emulate-specific controls live under the reserved /_emulate namespace.

Host-based routing

Hosted services are available on host-based routing. There are four address forms:

Form	Example	Purpose
Apex catalog	`https://emulators.dev`	The emulator catalog: a links-out landing page that lists every emulator and links to its host
Service host	`https://github.emulators.dev`	A single service, control plane only. Serves the service-level control plane and instance creation; provider routes require an instance
Instance host	`https://github.my-run.emulators.dev`	One stateful instance of a service. The provider base URL is the origin itself
Path form	`https://emulators.dev/github/my-run`	A compatibility form that routes to the same instance as the instance host

Create instances with POST /_emulate/instances: the server generates an unguessable name (an optional {"instance":"<prefix>"} body adds a readable prefix, so a CI run can request ci and get stripe.ci-4f2a….emulators.dev). The instance host form is preferred for public examples because the provider base URL is the origin, which matches a service-owned host.

The instance URL is a capability. Hosted instances have no authentication in front of them, so anyone holding the URL can read state, read the ledger, and mint credentials on that instance. Save the returned URLs rather than re-deriving the name, and never put real secrets into an emulator. Addressing a hand-picked instance host directly still works, but a short hand-picked name on the public host is guessable by anyone who picks the same one.

Apex catalog

The apex emulators.dev is the emulator catalog, not the docs site. It is served by the emulate-hosts worker through the console, which fetches GET /_emulate/services and renders the list. That endpoint returns a machine-readable catalog of every hosted service:

curl -s https://emulators.dev/_emulate/services

{
  "services": [
    {
      "id": "github",
      "name": "GitHub",
      "description": "Stateful GitHub API emulator.",
      "serviceHost": "https://github.emulators.dev",
      "instanceHostPattern": "https://github.<instance>.emulators.dev",
      "pathForm": "https://emulators.dev/github/<instance>",
      "manifest": "https://github.emulators.dev/_emulate/manifest"
    }
  ]
}

GET /_emulate/services is available from any host, so consoles and agents can discover what is deployed from the apex, a service host, or an instance host.

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. 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

Instance model

The emulate-hosts worker serves emulators.dev/* (the apex catalog) and *.emulators.dev/* (service and instance hosts). Each stateful 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.

POST https://github.emulators.dev/_emulate/instances

Instances are created lazily. Creating one returns the base URL, control base URL, and provider base URL for that instance, under a server-generated unguessable name; addressing an instance host for the first time also materializes it. See the Service Manifest for the instance shape and Request Ledger for what persists.

Hosted services

The hosted catalog includes all 13 services: GitHub, Vercel, Google, Okta, Microsoft Entra ID, Spotify, Slack, Apple, AWS, Resend, Stripe, MongoDB Atlas, and Clerk.

Docs subdomain

Docs are a separate site. They are deployed on the emulate-docs worker at docs.emulators.dev, and per-service docs live at https://docs.emulators.dev/<service>, which is the convention the manifest docsUrl follows. Because docs.emulators.dev is a more specific host than the apex, it wins for that hostname. The apex emulators.dev is the catalog, not the docs.