aimock is a TypeScript mock server that makes every AI provider, protocol, and service an application talks to answer on one local port, built for developers who need deterministic tests of LLM-backed software without API keys, network calls, or surprise bills.

What it is

aimock is mock infrastructure for AI application testing, published under the MIT licence by CopilotKit as the npm package @copilotkit/aimock. It lives in the TypeScript and Node.js ecosystem and presents itself as one package, one port, and zero dependencies. A single process stands in for the whole surface of a modern AI application: LLM providers, image generation and editing, text-to-speech, transcription, audio translation and generation, video generation, embeddings, MCP tools, A2A agents, AG-UI event streams, vector databases, search, rerank, and moderation. The suite is split into named mocks — LLMock, MCPMock, A2AMock, AGUIMock, VectorMock, and Services — that can be composed programmatically or started together.

The concrete problem it solves is test dependence on live third-party services. Instead of pointing a client at real OpenAI, Claude, Gemini, Bedrock, Azure, Vertex AI, Ollama, Cohere, or OpenRouter endpoints, a developer points SDKs at a local base URL such as ${mock.url}/v1 and sets a placeholder key. The same substitution applies to hosted vector databases, Tavily search, Cohere rerank, OpenAI moderation, and ElevenLabs TTS. The thing being replaced is the live API call itself, along with the accounts, keys, quota, latency, and billing that come with it.

Key capabilities

• LLMock answers for OpenAI Chat, Responses, and Realtime (both GA and Beta), Claude, Gemini REST/Live/Interactions/Embeddings, Bedrock, Azure, Vertex AI, Ollama chat and embeddings, Cohere chat and embed, OpenRouter chat and router, and ElevenLabs TTS.
• MCPMock serves MCP tools, resources, and prompts with session management, while A2AMock covers the agent-to-agent protocol with SSE streaming and AGUIMock emits AG-UI agent-to-UI event streams for frontend testing.
• VectorMock exposes Pinecone, Qdrant, and ChromaDB compatible endpoints, and the Services mock covers Tavily search, Cohere rerank, OpenAI moderation, and ElevenLabs TTS.
• The whole suite runs on one port with npx @copilotkit/aimock --config aimock.json, or through the programmatic API for composing only what a test needs.
• Record and Replay proxies real APIs, saves the responses as fixtures, and replays them deterministically without network access.
• Timing-aware recording captures per-frame arrival timestamps, and replay reproduces approximate timing from the recorded TTFT and inter-frame cadence, with a configurable --replay-speed multiplier. Chunk count on replay may differ from the recording; TTFT and average pace are what is preserved.
• Recorded token usage and cost come from the final usage frame of a streaming completion, so fixtures can support cost assertions.

Who uses it and how

• Frontend teams testing agent-to-UI behaviour use AGUIMock to drive AG-UI event streams without running a live agent backend.
• Test suites and CI pipelines use Record and Replay fixtures so runs stay deterministic and offline, with no provider keys present in the environment.
• Teams that assert on token usage and cost replay recorded completions whose usage frame was captured during recording.
• Developers integrating MCP tools or agent-to-agent flows exercise those protocols against MCPMock and A2AMock, including SSE streaming.
• Retrieval pipelines are tested against VectorMock's Pinecone, Qdrant, and ChromaDB endpoints alongside the search and rerank services.

Getting started

Install with npm install @copilotkit/aimock, then construct new LLMock({ port: 0 }), register responses such as mock.onMessage("hello", { content: "Hi there!" }), and call await mock.start(). To run the full suite instead, use npx @copilotkit/aimock --config aimock.json.

How it compares

No list of paid products that aimock replaces, and no comparable tools, are named in the facts available here, so it stands alone in this registry rather than being positioned against alternatives.

When to use it — and when not

Provider environment variables such as OPENAI_BASE_URL and OPENAI_API_KEY must be set before importing or constructing the client, because many SDKs cache the base URL at construction time; a client built first will call the real API and incur charges. Replay is approximate timing, not per-token fidelity, and the package was renamed from @copilotkit/llmock to @copilotkit/aimock in v1.7.0 while the exported class remains LLMock for back-compat, which can confuse newcomers. Anyone needing byte-exact streaming reproduction or per-token timing should not rely on replay for that purpose.

npm install @copilotkit/aimock

// The class is still named `LLMock` for back-compat after the v1.7.0 package
// rename from `@copilotkit/llmock` to `@copilotkit/aimock`.
import { LLMock } from "@copilotkit/aimock";

const mock = new LLMock({ port: 0 });
mock.onMessage("hello", { content: "Hi there!" });
await mock.start();

// Set env BEFORE importing/constructing the OpenAI (or other provider) client.
// Many SDKs cache the base URL at construction time — if the client is built
// before these are set, it will talk to the real API (surprise bills) instead
// of aimock.
process.env.OPENAI_BASE_URL = `${mock.url}/v1`;
process.env.OPENAI_API_KEY = "mock"; // SDK requires a value, even when base URL is mocked

// ... run your tests ...

await mock.stop();