---
title: "Getting Started"
description: "Local drop-in replacement services for CI and no-network sandboxes. Fully stateful, production-fidelity API emulation."
canonical_url: "https://emulate.dev/docs"
---
# Getting Started

Local drop-in replacement for Vercel, GitHub, Google, Slack, Apple, Microsoft, Okta, AWS, Resend, Stripe, MongoDB Atlas, Clerk, Linear, and Twilio APIs, plus OpenAI Responses, Chat Completions, and Anthropic Messages for AI apps. Built for CI and no-network sandboxes. Fully stateful, production-fidelity API emulation. Not mocks.

## Quick Start

```bash
npx emulate
```

All services listen on IPv4 loopback (`127.0.0.1`) by default. 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`
- **Linear** on `http://localhost:4012`
- **Twilio** on `http://localhost:4013`
- **AI** on `http://localhost:4014` (OpenAI Responses, Chat Completions, and Anthropic Messages at `/v1`)

## CLI

```bash
# 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 omitted service secrets into a private file
npx emulate start --seed config.yaml --generated-secrets-file .emulate-secrets.json

# 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

<table>
  <thead>
    <tr>
      <th>Flag</th>
      <th>Default</th>
      <th>Description</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td><code>-p, --port</code></td>
      <td><code>4000</code></td>
      <td>Base port (auto-increments per service)</td>
    </tr>
    <tr>
      <td><code>--host</code></td>
      <td><code>127.0.0.1</code></td>
      <td>Listening address; use <code>0.0.0.0</code> to allow network access</td>
    </tr>
    <tr>
      <td><code>-s, --service</code></td>
      <td>all</td>
      <td>Comma-separated services to enable</td>
    </tr>
    <tr>
      <td><code>--seed</code></td>
      <td>auto-detect</td>
      <td>Path to seed config (YAML or JSON)</td>
    </tr>
    <tr>
      <td><code>--base-url</code></td>
      <td>none</td>
      <td>Override the advertised base URL (supports <code>{'{service}'}</code> template)</td>
    </tr>
    <tr>
      <td><code>--portless</code></td>
      <td>off</td>
      <td>Serve over HTTPS through portless and register service aliases</td>
    </tr>
    <tr>
      <td><code>--generated-secrets-file</code></td>
      <td>none</td>
      <td>Generate omitted service secrets and write them to a new owner-only JSON file</td>
    </tr>
  </tbody>
</table>

The generated-secrets destination must not exist. emulate removes inherited ACLs, verifies effective owner-only access, and publishes the complete file before startup. Handled startup failures remove the invocation-owned artifact. A hard termination can leave a complete artifact that requires manual recovery. Linux requires `setfacl` and `getfacl` from the `acl` package. The flag fails closed when access controls cannot be verified and is not supported on Windows.

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

For access from a container or another machine, use `npx emulate start --host 0.0.0.0`. Set `--base-url` to a URL reachable by those clients when using OAuth redirects or other advertised URLs.

## Programmatic API

You can also use emulate as a library in your tests. See the [Programmatic API](/docs/programmatic-api) page for `createEmulator`, Vitest/Jest setup, and instance methods.

## Framework Integration

Embed emulators directly in your Next.js or Nuxt app so they run on the same origin. See the [Next.js Integration](/docs/nextjs) and [Nuxt Integration](/docs/nuxt) pages for setup instructions.

GitHub App flows expose secret-free installation-token metadata through an emulator-only inspection route. See the [GitHub documentation](/docs/github) for details.
