Open source · Apache 2.0

Every provider in CI. Zero cost.

Production-accurate streaming, errors and agent loops for every major provider, in CI. Deterministic, offline, no keys, no spend.

Run it now Read the Docs

ci · test run

# start the mock, run the suite, no keys, no spend
$ docker run -d -p 8100:8100 ghcr.io/vidaiuk/vidaimock  &&  pytest tests/agents/

  agents/test_langgraph_loop.py ....   [ tool loop terminates ]
  agents/test_openai_stream.py  ..     [ SSE wire-accurate ]
  agents/test_retry_on_429.py   ...    [ X-Mock-Status: 429 ]

  23 passed in 1.84s   ·   $0.00 spent   ·   offline

What it is

Not a record-and-replay stub. A simulation engine.

Real AI failures are about wire format, timing and loop behaviour, not just status codes. VidaiMock emulates the exact streaming payloads and per-token timing of real providers, so the things that break in production break in your tests too.

Batteries included

OpenAI, Anthropic, Gemini, Bedrock, Azure, Cohere, Mistral and Groq respond correctly with zero configuration. Start the mock and point your SDK at it.

Agentic loops terminate

It detects a tool result already in the history and switches to plain-text synthesis, so ADK / LangGraph / LangChain runs end naturally instead of looping forever.

SDK-level wire accuracy

The official SDKs iterate it with no compat shims. Streams are regression-tested byte-for-byte against captured real-provider wire format.

Zero to a local provider in 30 seconds

Point any SDK at a fake that behaves real.

Docker Compose is the recommended path — one compose file, an overrides/ directory next to it, isolated-mode via env var. A plain docker run or the binary work the same way when you want a quicker throwaway.

terminal · docker compose (recommended)

# grab the compose file and start the mock — bundled providers serve immediately
$ curl -O https://raw.githubusercontent.com/vidaiUK/VidaiMock/main/docker/docker-compose.yml
$ docker compose up -d

# override a provider or template — drop it under ./overrides/, restart
$ mkdir -p overrides/providers && vim overrides/providers/openai.yaml
$ docker compose restart

# lock the surface to ONLY your overrides — flip one env var
$ echo "VIDAIMOCK_ISOLATED=true" >> .env  &&  docker compose up -d

terminal · throwaway run or binary

# one-liner throwaway, no compose, no overrides
$ docker run --rm -p 8100:8100 ghcr.io/vidaiuk/vidaimock:latest

# or the binary — no Docker needed (macOS arm64 shown; Linux + Windows in the docs)
$ curl -LO https://github.com/vidaiUK/VidaiMock/releases/latest/download/vidaimock-macos-arm64.tar.gz
$ tar -xzf vidaimock-macos-arm64.tar.gz && cd vidaimock && ./vidaimock

# whichever path you took: force any status on a real provider route
$ curl -H "X-Mock-Status: 429" localhost:8100/v1/chat/completions \
    -d '{"model":"gpt-4","messages":[{"role":"user","content":"Hi"}]}'
  ← 429  {"error":{"type":"rate_limit_error", …}}

Signed multi-arch Docker image (~25MB distroless) or a ~7MB binary, no dependencies. YAML providers + Tera templates, overridable without recompiling. /health, /status and Prometheus /metrics built in.

The part most mocks skip

Agent loops that terminate, just like the real provider.

An agent framework wraps a model in a loop: model → tool_call → tool runs → tool_result → model → … A naïve mock either always returns a tool call (infinite loop) or never does (breaks tool tests). VidaiMock inspects the conversation and does the right thing on both sides.

→Tools defined, no result yet. It emits a tool_call / tool_use / functionCall in the calling provider's native shape.

→Tool result already in history. It switches to plain-text synthesis with the correct terminal signal, so the loop ends.

→All three providers. OpenAI role:tool, Anthropic tool_result blocks, Gemini functionResponse parts are all recognised.

→Real CI value. Run Google ADK, LangGraph or LangChain Runner loops end-to-end with zero live-provider spend.

Why teams adopt it

Deterministic CI, production-accurate behaviour.

→Provider-shaped errors. Inject a 400, 429, 500 by header, URL query or chaos probability; every one returns the real OpenAI / Anthropic / Gemini error envelope so SDK error paths are tested honestly.

→Typed SSE streaming. OpenAI Responses typed events, Anthropic's 7-event lifecycle, Gemini's terminal-chunk pattern, and final usage chunks, all wire-accurate.

→Customisable without a rebuild. Bundled providers and Tera templates are embedded defaults; drop a file in your config dir and disk beats embedded.

→The dev environment for VidaiServer. The same simulation engine that powers the mock drives the control plane's latency and failure modelling.

Spin one up in 30 seconds.

Open-source, Docker or binary. The docs cover install, agentic testing, chaos and streaming.

Read the Docs View on GitHub