# Switching from VidaiMock to aimock

VidaiMock is a capable Rust binary with broad provider support. aimock matches that coverage and adds what VidaiMock can’t — a programmatic TypeScript API, WebSocket support, fixture files, request journal, and MCP/A2A/AG-UI/Vector mocking.

## The quick switch

The CLI flags map directly. Swap the binary name, adjust the flag names, and go:

VidaiMock shell

    vidaimock --port 4010 --template-dir ./templates

aimock (equivalent) shell

    npx -p @copilotkit/aimock llmock -p 4010 -f ./fixtures

aimock (equivalent) shell

    docker run -d -p 4010:4010 \
      -v ./fixtures:/fixtures \
      ghcr.io/copilotkit/aimock \
      -p 4010 -f /fixtures -h 0.0.0.0

### Fixture format comparison

VidaiMock uses Tera templates (`.tera`) to build responses dynamically. aimock uses plain JSON fixture files — no template language, no compilation step.

VidaiMock — Tera template tera

    {
      "model": "{{ model }}",
      "choices": [{
        "message": {
          "role": "assistant",
          "content": "Hello from VidaiMock"
        }
      }]
    }

aimock — JSON fixture json

    {
      "match": { "userMessage": "hello" },
      "response": { "content": "Hello from aimock" }
    }

aimock fixtures are declarative: you specify what to match and what to return. The server handles model names, streaming format, and provider-specific envelope generation automatically.

## What you gain

API

### Programmatic API

Import `LLMock` in TypeScript/JavaScript and configure fixtures, assertions, and lifecycle in code — no process spawning needed.

Transport

### WebSocket APIs

Built-in support for OpenAI Realtime, OpenAI Responses WS, and Gemini Live — three WebSocket protocols out of the box.

Testing

### Request journal

Every request is recorded with full headers, body, matched fixture, and timing. `getRequests()` lets you assert on what your app actually sent.

Protocols

### MCP / A2A / AG-UI / Vector

Mock your entire AI stack — LLM, MCP, A2A, AG-UI, vector — on one port.

Capture

### Record & replay

Proxy to real APIs, capture responses as fixtures, then replay deterministically in CI. No manual fixture authoring required.

CI

### Drift detection

Automated three-way conformance testing against live provider APIs. Catch breaking changes before your users do.

Format

### Structured output

JSON mode and `response_format` matching for structured responses — match on schema, return typed JSON.

Stateful

### Sequential responses

Return different responses on successive calls to the same endpoint. Model multi-turn conversations and retry scenarios.

## Comparison table

Capability | VidaiMock | aimock
--- | --- | ---
Programmatic API | No (binary only) | Yes (TypeScript/JS)
WebSocket APIs | No | Built-in (3 protocols)
Request journal | No | Built-in
MCP / A2A / AG-UI / Vector | No | Built-in
Record & replay | No | Built-in
Drift detection | No | Automated CI
LLM providers | 12+ | 12+
Prometheus metrics | Yes | Yes
Chaos testing | Partial | Built-in (3 modes)
Docker | Yes | Yes
Streaming physics | Yes | Built-in (ttft/tps/jitter)
Dependencies | Zero (Rust) | Zero (Node.js builtins)

## CLI / Docker quick start

Install & run shell

    # Run the mock server (flag-driven llmock bin)
    npx -p @copilotkit/aimock llmock -p 4010 -f ./fixtures

    # Point your app at it
    export OPENAI_BASE_URL=http://localhost:4010/v1
    export OPENAI_API_KEY=mock-key

With a config file shell

    # Full config-driven setup (LLM + MCP + A2A + AG-UI on one port)
    npx @copilotkit/aimock --config aimock.json --port 4010

Docker run shell

    # Pull and run from GitHub Container Registry
    docker pull ghcr.io/copilotkit/aimock:latest

    docker run -p 4010:4010 \
      -v $(pwd)/fixtures:/fixtures \
      ghcr.io/copilotkit/aimock -f /fixtures -h 0.0.0.0

Note: `--config` (and the `convert` subcommand) are only available through the `npx @copilotkit/aimock` entrypoint or a local install. The published Docker image at `ghcr.io/copilotkit/aimock` runs the narrower flag-driven `llmock` CLI — for config-driven mode, run aimock on your host via npx, or install `@copilotkit/aimock` inside your own container.

Config-driven (local / npx) shell

    # Full config-driven setup (LLM + MCP + A2A + AG-UI on one port)
    npx @copilotkit/aimock --config aimock.json --port 4010

docker-compose.yml yaml

    services:
      aimock:
        image: ghcr.io/copilotkit/aimock:latest
        command: ["-f", "/app/fixtures", "-h", "0.0.0.0"]
        ports:
          - "4010:4010"
        volumes:
          - ./fixtures:/app/fixtures:ro

      app:
        build: .
        environment:
          OPENAI_BASE_URL: http://aimock:4010/v1
          OPENAI_API_KEY: mock-key
        depends_on:
          - aimock