⚡ Mockbird

The AI-native local mock server — fixtures, OpenAPI, proxy recording, and a live inspector UI. Zero config, instant start, fully offline-capable.

90-second quickstart

# 1. Start immediately — no config, no account, no build step
npx mockbird

# 2. Open the live inspector in your browser
#    → http://localhost:3000/__mockbird__

# 3. In another terminal, hit any path. With no mocks yet you get a helpful
#    404 that tells you exactly how to add one — and it streams to the inspector.
curl http://localhost:3000/api/anything

Now give it something real to serve. The fastest win is proxy recording — point Mockbird at any public API and it forwards the request, then saves the response as a fixture for instant offline replay:

npx mockbird --proxy https://jsonplaceholder.typicode.com
curl http://localhost:3000/todos/1   # forwarded once, recorded as a fixture
curl http://localhost:3000/todos/1   # replayed locally — no upstream call

Prefer generated data? Enable an AI provider (Ollama runs fully offline). Have a spec? Point schemaPath at your OpenAPI file. Every request shows up live in the inspector either way.

✨ Features

• 🚀 Instant start — npx mockbird boots a working server and inspector with zero config.
• 📦 Smart fixtures — deterministic, hash-based replay/record; auto-saved from proxy and AI.
• ↗️ Proxy recording — forward to a real API and record responses as fixtures for offline replay.
• 📋 OpenAPI support — auto-serve example responses from an OpenAPI 3.x schema (path params included).
• 🤖 AI fallback — no fixture, schema, or proxy? Generate a realistic response via Ollama (local), Grok, or Claude.
• 🖥️ Live inspector — dark-mode dashboard streaming requests over WebSocket.
• 🩺 doctor command — one command tells you if your environment is ready.
• 🔒 Security-hardened — SSRF guards, path-traversal prevention, rate limiting, header stripping, secret redaction, and security headers.
• 📡 Programmatic API — embed the server in your Node.js app (ESM and CommonJS).
• ✈️ Offline / air-gapped — with Ollama, the entire stack runs with no network access.

📦 Installation

# Run without installing
npx mockbird

# Or install globally
npm install -g mockbird

Requires Node.js 18+. No native dependencies.

🔀 Route resolution order

Mockbird resolves each request in priority order and stops at the first match:

1. Fixture — a saved response (manual, proxy-recorded, or AI-generated).
2. OpenAPI schema — an example response from your spec.
3. Proxy — forward to the real API (optionally recording the response).
4. AI fallback — generate a realistic response on the fly.

If none apply, you get a helpful 404 explaining what to configure. (Note: when a proxy target is set it handles everything not matched by a fixture or schema, so the AI fallback runs only when no proxy is configured.)

⚙️ Configuration

Zero config is the default. To customize, run npx mockbird init to scaffold a mockbird.config.mjs:

/** @type {import('mockbird').MockbirdConfig} */
export default {
    port: 3000,
    fixturesDir: './fixtures',
    // schemaPath: './openapi.json',

    // proxy: {
    //   target: 'https://api.example.com',
    //   record: true,
    //   forwardAuth: false,
    //   recordStatus: 'all',   // 'all' | 'success' | 'success-redirect'
    // },

    ai: {
        provider: 'none', // 'ollama' | 'grok' | 'claude' | 'none'
        model: 'llama3.2',
        baseUrl: 'http://localhost:11434',
        temperature: 0.7,
        maxTokens: 800,
    },
};

Config files are discovered in this order: mockbird.config.mjs → .js → .ts → .json. .mjs/.js/.json load on any supported Node; .ts config only loads on a runtime that strips types (Node ≥ 23.6 or a loader like tsx). A config that exists but fails to load or validate produces a clear, actionable error rather than silently falling back to defaults.

Full reference: docs/configuration.md.

AI providers

| Provider | Setup | Cost | Offline | | ---------- | ------------------------------------------------- | ------------ | ------- | | Ollama | ollama serve + ollama pull llama3.2 | Free (local) | ✅ Yes | | Grok | set GROK_API_KEY | API pricing | ❌ No | | Claude | set ANTHROPIC_API_KEY | API pricing | ❌ No |

Secrets: API keys are read only from environment variables — never from config files, never logged, never returned by the API. See docs/ai-providers.md, including a fully-offline Ollama setup for air-gapped environments.

🩺 Doctor

npx mockbird doctor

Checks your Node version, config validity, port availability, fixtures directory, and AI provider reachability, then prints a green/red report.

🖥️ Inspector UI

Open http://localhost:3000/__mockbird__:

• Live requests — real-time request/response stream over WebSocket.
• Fixtures — browse and delete saved fixtures.
• AI Studio — regenerate a mock for a given method + path.

The UI ships pre-built in the npm package — a global install serves it with no separate build step.

📊 How it compares

A quick, honest summary. Every tool here is good at what it does; Mockbird's niche is zero-config + AI generation + a live inspector, fully offline. Capabilities evolve — verify against each project's current docs.

| Capability | Mockbird | Mockoon | WireMock | Prism | MSW | Postman mocks | | --------------------- | :-------: | :-----: | :------: | :---: | :--: | :-----------: | | Zero-config start | ✅ | ✅ | ⚠️ | ⚠️ | ❌ | ⚠️ | | AI response generation| ✅ | ❌ | ❌ | ❌ | ❌ | ❌ | | Proxy record → replay | ✅ | ✅ | ✅ | ❌ | ❌ | ⚠️ | | OpenAPI examples | ✅ | ✅ | ⚠️ | ✅ | ⚠️ | ✅ | | Live request inspector| ✅ | ✅ | ⚠️ | ❌ | ⚠️ | ⚠️ | | Offline / air-gapped | ✅ | ✅ | ✅ | ✅ | ✅ | ❌ |

✅ built-in · ⚠️ partial / needs setup · ❌ not offered

🔒 Security

Mockbird is hardened for local development:

• SSRF protection — Ollama is restricted to localhost/127.0.0.1; remote providers must use https://; proxy targets must use https://.
• Path traversal — fixture file operations resolve and validate paths (path.resolve + realpathSync), reject .. and absolute paths.
• Rate limiting — 10 AI calls/min per endpoint; 30/min on the internal API.
• Body limits — a 1 MB cap, enforced by a Content-Length pre-check on all routes and a bounded stream reader on the endpoint that buffers input, so chunked requests without Content-Length can't bypass it.
• CORS — locked to localhost/127.0.0.1 (no wildcards); the WebSocket validates origin the same way.
• Header stripping — Authorization, Cookie, and related headers are stripped from proxied requests unless forwardAuth is enabled.
• Redaction — bearer tokens and API-key-shaped strings are redacted from logs and inspector events.
• Security headers — X-Content-Type-Options, X-Frame-Options, Referrer-Policy, and a CSP on the inspector.

See SECURITY.md to report a vulnerability.

📡 Programmatic API

import { createServer } from 'mockbird'; // or: const { createServer } = require('mockbird')

const server = await createServer({
    port: 3000,
    fixturesDir: './fixtures',
    ai: { provider: 'ollama', model: 'llama3.2', temperature: 0.7, maxTokens: 800 },
});

// server.app    — the Hono instance
// server.close() — shut down the HTTP + WebSocket servers

Full guide: docs/programmatic-api.md.

📚 Documentation

• Configuration reference
• Fixtures
• Proxy recording
• OpenAPI
• AI providers (incl. offline Ollama)
• Programmatic API
• Extending Mockbird (plugins & hooks)

🧪 Development

npm install
npm test            # run the test suite (Vitest)
npm run lint        # ESLint
npm run typecheck   # tsc --noEmit
npm run build:all   # build the library + inspector UI
npm run smoke       # pack, install into a temp dir, and boot-test the tarball

🤝 Contributing

Contributions welcome! Please read CONTRIBUTING.md and our Code of Conduct.

📄 License

Apache 2.0 © 2026 Favaz Musthafa and Mockbird contributors. See NOTICE.