aimock — mock everything your AI app talks to

# Deterministic mock infrastructure for AI apps

Start with LLM mocking. Add MCP, A2A, vector, and more when you need them. The aimock suite grows with your stack.

$ `npx -p @copilotkit/aimock llmock -f ./fixtures`
or
$ `docker run -v $(pwd)/fixtures:/fixtures -p 4010:4010 ghcr.io/copilotkit/aimock -h 0.0.0.0 -f /fixtures`

Or install as a library: `npm install @copilotkit/aimock`

fixture.json

    {
      "match": {
        "userMessage": "Hello"
      },
      "response": {
        "content": "Hi there! How can I help?"
      },
      "opts": {
        "chunkSize": 10,
        "latency": 1000
      }
    }

terminal
Record & Replay

## From zero to fixtures in one command

1

### Record

Proxy unmatched requests to real APIs and capture every response.

2

### Save

Fixtures written to disk automatically as clean, editable JSON.

3

### Replay

Deterministic responses in CI, forever. No API keys, no flakiness.

Learn about Record & Replay →
terminal

    $ npx -p @copilotkit/aimock llmock --record --provider-openai https://api.openai.com

    ⚡ Listening on http://localhost:4010

    ⚠ NO FIXTURE MATCH — proxying to
      https://api.openai.com/v1/chat/completions

    ✓ Recorded → fixtures/recorded/openai-2026-03-31T22:15:00.json

    ⚡ Fixture match — replaying from disk

## Your AI app talks to more than just LLMs.
aimock mocks all of them.

🔌 MCP Tools
🤝 A2A Agents
🖥 AG-UI
📦 Vector DBs
🔍 Search & Rerank
🛡 Moderation

One JSON config. One port. Every service your AI app depends on.

aimock.json

    {
      "llm": {
        "fixtures": "./fixtures/llm",
        "providers": ["openai", "claude", "gemini"]
      },
      "mcp": {
        "tools": "./fixtures/mcp/tools.json",
        "resources": "./fixtures/mcp/resources.json"
      },
      "a2a": {
        "agents": "./fixtures/a2a/agents.json"
      },
      "vector": {
        "provider": "pinecone",
        "fixtures": "./fixtures/vector"
      }
    }

terminal

    $ npx @copilotkit/aimock --config aimock.json

    ⚡ aimock v1.16.0

    ✓ LLM    mounted at  /v1/chat/completions
    ✓ LLM    mounted at  /v1/messages
    ✓ LLM    mounted at  /v1/embeddings
    ✓ MCP    mounted at  /mcp/tools/*
    ✓ A2A    mounted at  /a2a/agents/*
    ✓ Vector mounted at  /vectors/*

    ⚡ Listening on http://localhost:4010
       6 services · 24 fixtures loaded

## Everything you need

📡

### Every Major LLM Provider

OpenAI, Claude, Gemini, Gemini Interactions, Bedrock, Azure, Vertex AI, Ollama, Cohere, ElevenLabs — full streaming and embeddings support for every provider.

🔌

### MCP Protocol

Mock tools, resources, and prompts with full session management. Test your MCP integrations without running real tool servers.

🤝

### A2A Protocol

Agent cards, message routing, and SSE streaming. Mock multi-agent interactions with deterministic responses.

🖥

### AG-UI Protocol

Mock agent-to-UI event streams for CopilotKit frontend testing.

📦

### Vector Databases

Pinecone, Qdrant, and ChromaDB compatible. Mock similarity search, upserts, and index operations with fixtures.

💥

### Chaos Testing

Drop, malformed, or disconnect at any probability. Verify your app gracefully handles every failure mode.

🎨

### Multimedia APIs

Image generation and editing, text-to-speech (OpenAI + ElevenLabs), audio transcription and translation, non-speech audio generation, and video generation — mock every multimedia endpoint with fixtures.

🧪

### Vitest & Jest Plugins

Zero-config `useAimock()` with auto server lifecycle, env var patching, and match count reset.

📊

### Drift Detection

Fixtures stay accurate as providers evolve. Fixes ship before your tests break.

## Your mocks never go stale

LLM providers change their response formats without warning. aimock catches it within 24 hours and ships the fix before your tests break.

1

### Real API calls

Daily CI hits actual OpenAI, Anthropic, Gemini endpoints to detect response format changes.

2

### Compare & detect

Response schemas are validated against aimock's builders. Any drift is flagged automatically.

3

### Fix & ship

Drift detected → fixtures, builders, skills, and docs updated → PR shipped. Always current, within a day.

Learn about drift detection →

## How aimock compares

Capability | aimock | MSW | VidaiMock | mock-llm | piyook/llm-mock | mokksy/ai-mocks
--- | --- | --- | --- | --- | --- | ---
Cross-process interception | Real server ✓ | In-process only | ✓ | ✓ (Docker) | ✓ | ✓ (Ktor)
Chat Completions SSE | Built-in ✓ | manual | ✓ | ✓ | ✓ | ✓
Responses API SSE | Built-in ✓ | manual | ✓ | ✓ | ✓ | ✓
Claude Messages API | Built-in ✓ | manual | ✓ | ✗ | ✓ | ✓
Gemini streaming | Built-in ✓ | manual | ✓ | ✗ | ✓ | ✓
Multi-provider support | 14 providers ✓ | manual | 12 providers | OpenAI only | OpenAI only | 5 providers
WebSocket APIs | Built-in ✓ | ✗ | ✗ | ✗ | ✗ | ✗
Embeddings API | Built-in ✓ | ✗ | ✓ | ✗ | ✓ | ✓
Image generation | Built-in ✓ | ✗ | ✓ | ✗ | ✗ | ✗
Image editing | Built-in ✓ | ✗ | ✗ | ✗ | ✗ | ✗
Text-to-Speech | Built-in ✓ | ✗ | ✗ | ✗ | ✗ | ✗
Audio transcription | Built-in ✓ | ✗ | ✗ | ✗ | ✗ | ✗
Audio translation | Built-in ✓ | ✗ | ✗ | ✗ | ✗ | ✗
Non-speech audio | Built-in ✓ | ✗ | ✗ | ✗ | ✗ | ✗
Video generation | Built-in ✓ | ✗ | ✗ | ✗ | ✗ | ✗
AG-UI event mocking | Built-in ✓ | ✗ | ✗ | ✗ | ✗ | ✗
MCP tool mocking | Built-in ✓ | ✗ | ✗ | ✗ | ✗ | ✗
A2A agent mocking | Built-in ✓ | ✗ | ✗ | ✗ | ✗ | ✓
Vector DB mocking | Built-in ✓ | ✗ | ✗ | ✗ | ✗ | ✗
Search & rerank | Built-in ✓ | ✗ | ✗ | ✗ | ✗ | ✗
Record & replay | Built-in ✓ | ✗ | ✗ | ✗ | ✗ | ✗
Drift detection | ✓ | ✗ | ✗ | ✗ | ✗ | ✗
Sequential / stateful responses | Built-in ✓ | manual | ✓ | ✓ | ✗ | ✗
Request journal | ✓ | manual | ✓ | ✗ | ✓ | ✗
Error injection | ✓ | ✓ | partial | ✗ | ✗ | ✗
Chaos testing | Built-in ✓ | ✗ | ✓ | ✗ | ✗ | ✗
Streaming physics | Built-in ✓ | ✗ | ✓ | ✗ | ✗ | ✗
Structured output / JSON mode | Built-in ✓ | manual | ✓ | ✗ | ✗ | ✗
Programmatic API | ✓ (TypeScript/JS) | ✓ (TypeScript/JS) | No (binary only) | ✗ | ✗ | ✓ (Kotlin/JVM)
Fixture files | JSON ✓ | Code-only | Tera templates | YAML config | JSON templates | ✗
GitHub Action | Built-in ✓ | ✗ | ✗ | ✗ | ✓ | ✓
Vitest / Jest plugins | Built-in ✓ | ✗ | ✗ | ✗ | ✗ | ✗
Docker + Helm | Both ✓ | ✗ | Docker only | ✓ (Both) | Docker only | ✗
Prometheus metrics | Built-in ✓ | ✗ | ✓ | ✗ | ✗ | ✗
Streaming usage chunks | Built-in ✓ | ✗ | ✓ | ✗ | ✗ | ✗
Rate limiting headers | Built-in ✓ | ✗ | ✗ | ✗ | ✗ | ✗
Dependencies | Zero ✓ | ~300KB | Zero (Rust) | Node+Express | Minimal | JVM (Kotlin)

## Ready to switch? We got you.

Step-by-step migration guides for every major mock tool.

MSW VidaiMock mock-llm piyook Python Mokksy openai-responses

## Built for production

AG-UI uses aimock for its end-to-end test suite, verifying AI agent behavior across LLM providers with fixture-driven responses in the codebase. Browse the example fixtures to get started.