Emulate

Emulate: production-fidelity service emulators

@executor-js/emulate (our fork of Vercel Labs' emulate) provides stateful, wire-level emulators for 16 services: github vercel google okta microsoft spotify slack apple aws resend stripe mongoatlas clerk x workos autumn. These are not mocks: real SDKs and real product code run against them unmodified — the cloud e2e target points the actual WorkOS SDK (sealed sessions, JWKS, hosted AuthKit login) and Autumn billing at emulators and exercises the product's real auth code.

This repo only consumes the published npm package. There is no vendor/emulate submodule — everything imports @executor-js/emulate from npm. The emulator source is its own standalone project; to change or deploy an emulator, see "Changing or deploying an emulator" at the bottom.

Two ways to get one

Local, programmatic (what e2e/setup/cloud.boot.ts does):

import { createEmulator } from "@executor-js/emulate";
const github = await createEmulator({ service: "github", port: 4501 });
// github.url, await github.close() — plus the full typed client below

baseUrl sets the advertised origin (redirects, form actions, spec servers) when a proxy fronts the emulator — the bind stays on port.

Attach to a running one (another process, or hosted on Cloudflare with Durable Object state at https://<service>.<instance>.emulators.dev — catalog at GET https://emulators.dev/_emulate/services). Service hosts (https://<service>.emulators.dev) are control plane only, with no shared default instance behind them: create a private instance first and connect to the returned providerBaseUrl.

import { connectEmulator } from "@executor-js/emulate";
const created = await fetch("https://resend.emulators.dev/_emulate/instances", { method: "POST" });
const { providerBaseUrl } = await created.json();
const resend = await connectEmulator({ baseUrl: providerBaseUrl });
// optional: { service: "resend" } verifies the manifest on connect

In e2e scenarios use createEmulatorInstance from e2e/src/emulator-instance.ts, which wraps this.

The typed control-plane client

Both createEmulator and connectEmulator return the same EmulatorClient surface (since 0.7.0) — use it instead of hand-rolling /_emulate fetches:

The same routes exist as raw HTTP under /_emulate/* (start at GET /_emulate/quickstart, written for agents) for curl/browser use — but in TypeScript, reach for the client; the types are the point.

Recipes

Test an integration end-to-end for real (the connect-handoff pattern): client.credentials.mint(...) → register client.openapiUrl with the product → invoke a tool through the product → find the call in client.ledger.list() (match on entry.request.body / operationId). The ledger is the proof — "the product made this exact upstream call with this auth" — which beats asserting on the product's own response.

Real OAuth/OIDC flows: google/okta/microsoft/apple/clerk/workos mint OAuth clients and run real authorize/token endpoints. The WorkOS emulator additionally serves hosted AuthKit login pages (any email signs in — users are minted on the fly, no password), an OAuth authorization server for MCP clients, and Vault KV. Real SDK + WORKOS_API_URL override = the product's untouched auth code against it. Set EMULATE_WORKOS_AUDIENCE=<client_id> before createEmulator so minted MCP access tokens carry the right audience.

A live, human-pokeable cloud instance with zero .env: cd e2e && bun run cli up cloud --share — WorkOS + Autumn emulators + the app's real dev stack (recipe in e2e/setup/cloud.boot.ts), fronted with tailscale HTTPS.