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

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