Getting Started

Local drop-in replacement for Kakao, Naver, Toss Payments, Firebase, Supabase, Asana, Linear, Autumn, GitLab, PostHog, Spotify, WorkOS, and X APIs. Built for CI and no-network sandboxes. Fully stateful, production-fidelity API emulation. Not mocks.

Quick start

npx @pleaseai/emulate

All services start with sensible defaults — no config file needed:

Service	Port	Emulated surface
Kakao	4000	OAuth 2.0 (kauth), user API, KakaoTalk self-memo send (kapi)
Naver	4001	Naver Login OAuth (issue/refresh/delete), profile API (/v1/nid/me)
Toss Payments	4002	Payment confirm/lookup/cancel, order lookup, checkout simulation, webhooks
Firebase	4003	Auth (Identity Toolkit REST), Secure Token, FCM v1
Supabase	4004	GoTrue Auth (signup/token/user), PostgREST table CRUD + filters
Asana	4005	Workspaces, teams, projects, sections, tasks, tags, stories, webhooks
Linear	4006	Linear GraphQL API (read-only) with Relay pagination
Autumn	4007	Billing: customers, balances, plans, attach, hosted checkout
GitLab	4008	GitLab GraphQL endpoint with real-schema introspection
PostHog	4009	Event capture, read API, OAuth 2.0 with dynamic client registration
Spotify	4010	OAuth client credentials, catalog search, artists, albums, tracks
WorkOS	4011	User Management, organizations, OAuth/OIDC, Vault KV
X	4012	X API v2: OAuth 2.0 PKCE, tweets, users, timelines

CLI

# Start all services (zero-config)
npx @pleaseai/emulate

# Start specific services
npx @pleaseai/emulate --service kakao,tosspayments

# Custom base port
npx @pleaseai/emulate --port 3000

# Use a seed config file
npx @pleaseai/emulate --seed emulate.config.yaml

# Generate a starter config
npx @pleaseai/emulate init

# Generate config for a specific service
npx @pleaseai/emulate init --service kakao

# List available services
npx @pleaseai/emulate list

Options

Flag	Default	Description
-p, --port <port>	4000	Base port (auto-increments per service)
-s, --service <services>	all	Comma-separated services to enable
--seed <file>	auto-detect	Path to seed config (YAML or JSON)
--base-url <url>	—	Override base URL (supports {service} interpolation)
--portless	off	Serve over HTTPS via portless (auto-registers aliases)

When a single service is started with --service, it runs on the base port. When multiple services run together, ports are assigned sequentially from the base port in registry order.

Running from source

Tool versions are pinned with mise — mise install provisions bun and node. (Without mise, any recent bun works.)

mise install
bun install
bun run build

# Start every service
bun packages/emulate/dist/index.js

# Start specific services only
bun packages/emulate/dist/index.js --service kakao,tosspayments

Pointing your app at the emulator

To use an emulator, only the base URL your SDK talks to needs to change:

• Firebase: FIREBASE_AUTH_EMULATOR_HOST=localhost:4003
• Supabase: createClient("http://localhost:4004", anonKey)
• Everything else: set the service base URL to http://localhost:<port>

Next steps

• Configuration — seed apps, users, and table data from YAML
• Programmatic API — embed emulators in your test suite
• Authentication — how tokens and OAuth flows work
• HTTPS with portless — trusted https://<service>.emulate.localhost URLs