Getting Started

Local drop-in replacement for Vercel, GitHub, Google, Slack, Apple, Microsoft, AWS, Okta, MongoDB Atlas, Resend, and Stripe APIs. Built for CI and no-network sandboxes. Fully stateful, production-fidelity API emulation. Not mocks.

Quick Start

npx emulate

All services start with sensible defaults. No config file needed:

Vercel on http://localhost:4000
GitHub on http://localhost:4001
Google on http://localhost:4002
Slack on http://localhost:4003
Apple on http://localhost:4004
Microsoft on http://localhost:4005
Okta on http://localhost:4006
AWS on http://localhost:4007
Resend on http://localhost:4008
Stripe on http://localhost:4009
MongoDB Atlas on http://localhost:4010
Clerk on http://localhost:4011
Spotify on http://localhost:4012
PostHog on http://localhost:4016

Control Plane

Every service exposes a public control plane under /_emulate.

Route	Purpose
`GET /_emulate`	Human-readable landing page for the service instance
`GET /_emulate/manifest`	Machine-readable service manifest with supported surfaces, auth capabilities, and spec coverage
`GET /_emulate/quickstart`	Plain-text instructions for humans and agents
`GET /_emulate/specs`	Advertised specs and protocol surfaces
`GET /_emulate/coverage`	Per-operation spec coverage with a summary by status (generated, hand-authored, partial, unsupported)
`GET /_emulate/connections`	Copyable SDK, CLI, env, and curl snippets resolved against this instance (optional `?token=`, `?client_id=`, `?client_secret=`)
`GET /_emulate/openapi`	Redirect to the advertised OpenAPI document when one exists
`GET /_emulate/graphql`	Return the GraphQL endpoint when the service exposes one
`GET /_emulate/mcp`	Return the MCP endpoint when the service exposes one
`GET /_emulate/state`	Current emulator store snapshot
`GET /_emulate/ledger`	Recent API calls with sensitive fields redacted. See Request Ledger
`DELETE /_emulate/ledger`	Clear the request ledger
`POST /_emulate/faults`	Arm a one-shot or counted fault against matching provider requests
`GET /_emulate/faults`	List armed faults with remaining counts
`DELETE /_emulate/faults`	Clear all armed faults
`DELETE /_emulate/faults/:id`	Clear one armed fault
`GET /_emulate/logs`	Webhook deliveries plus the most recent provider requests
`POST /_emulate/reset`	Reset state, webhooks, and the request ledger, then replay seed data
`POST /_emulate/seed`	Add runtime seed data using the service seed schema
`POST /_emulate/credentials`	Create bearer tokens, API keys, OAuth clients, or client-credentials apps where supported
`POST /_emulate/instances`	Return URLs for a lazily created hosted instance

The manifest advertises only the surfaces that match the real service. Specs such as OpenAPI, GraphQL, MCP, OAuth metadata, and Google discovery documents can inform an emulator, but they are not treated as proof that every protocol exists for every service. The Service Manifest is the single source of truth for what each emulator supports.

Service host

A bare service host such as https://github.emulators.dev (no instance) serves a service-level control plane so it is useful before you create an instance: GET /_emulate, /_emulate/manifest, /_emulate/quickstart, /_emulate/specs, /_emulate/coverage, /_emulate/connections, /_emulate/openapi, and POST /_emulate/instances.

Service catalog

GET /_emulate/services returns a machine-readable catalog of every hosted service, including its id, name, description, service host, instance host pattern, path form, and manifest URL. It is available from any host so consoles and agents can discover what is deployed. See Deployment.

Credential creation follows each service's real shape. GitHub can mint bearer tokens for users, Spotify creates client credentials apps, OAuth/OIDC providers create clients, Stripe and Resend create API-key style credentials, and AWS advertises provider-specific SDK credentials.

Deployed Instances

Hosted services are available on host-based routing. Cloudflare deployments support service hosts, instance hosts, and a compatibility path form:

https://github.emulators.dev               # service host
https://github.my-instance.emulators.dev   # instance host
https://emulators.dev/github/my-instance    # path form

The instance host and path form route to the same stateful service instance. The instance host form is preferred for public examples because the provider base URL is the origin itself, which better matches service-owned hosts. The control plane for the instance host form lives at https://github.my-instance.emulators.dev/_emulate.

See Deployment for the host-based routing model, the emulate-hosts Cloudflare worker, and the Durable Object instance model.

CLI

# Start all services (zero-config)
npx emulate

# Start specific services
npx emulate --service vercel,github

# Custom port
npx emulate --port 3000

# Use a seed config file
npx emulate --seed config.yaml

# Generate a starter config
npx emulate init

# Generate config for a specific service
npx emulate init --service github

# List available services
npx emulate list

Options

Flag	Default	Description
`-p, --port`	`4000`	Base port (auto-increments per service)
`-s, --service`	all	Comma-separated services to enable
`--seed`	auto-detect	Path to seed config (YAML or JSON)

The port can also be set via EMULATE_PORT or PORT environment variables.

Programmatic API

You can also use emulate as a library in your tests. See the Programmatic API page for createEmulator, Vitest/Jest setup, and instance methods.

Next.js Integration

Embed emulators directly in your Next.js app so they run on the same origin. See the Next.js Integration page for setup instructions.