aimock CLI

Configure all your mocks in one JSON file and serve them on a single port — LLM providers, MCP, A2A, AG-UI, vector databases, and services.

Quick Start

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

# --config is an aimock-CLI feature, not available in the published image.
# Run aimock on your host via npx (or install @copilotkit/aimock in your
# own container image) to use the config-driven CLI:
$ npx @copilotkit/aimock --config aimock.json --port 4010 --host 0.0.0.0

# If you only need flag-driven fixture serving, the published image works:
$ docker run -d -p 4010:4010 \
  -v ./fixtures:/fixtures \
  ghcr.io/copilotkit/aimock \
  -f /fixtures -h 0.0.0.0

Note: The published Docker image (ghcr.io/copilotkit/aimock) runs the flag-driven llmock CLI (ENTRYPOINT node dist/cli.js), which does not support --config or the convert subcommand. For config-driven mode, run aimock on your host via npx or install @copilotkit/aimock inside your own image.

Config File Format

The config file is a JSON object describing which services to run and how to configure them. The llm section configures the core LLMock server. Additional services are mounted at path prefixes.

{
  "llm": {
    "fixtures": "./fixtures",
    "latency": 0,
    "chunkSize": 20,
    "logLevel": "info",
    "validateOnLoad": true,
    "metrics": true,
    "strict": false
  },
  "services": {
    "/mcp": {
      "type": "mcp",
      "tools": "./mcp-tools.json"
    },
    "/a2a": {
      "type": "a2a",
      "agents": "./a2a-agents.json"
    }
  }
}

Config Fields

Recording Config (llm.record)

When llm.record is present, aimock proxies unmatched requests to real providers and saves the responses as fixtures. See Record & Replay for full details.

{
  "llm": {
    "fixtures": "./fixtures",
    "record": {
      "providers": {
        "openai": "https://api.openai.com",
        "anthropic": "https://api.anthropic.com"
      },
      "fixturePath": "./fixtures/recorded",
      "recordFullModelVersion": false
    }
  }
}

CLI Flags

Single-Port Routing

All services share one port. Requests are routed by path prefix. LLM endpoints live at the root, mounted services at their configured prefix:

Path stripping is automatic — a request to /mcp/tools/list arrives at the MCP service as /tools/list.

Docker Usage

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

# --config isn't available in the published Docker image's llmock entrypoint.
# Run aimock locally with npx to load config.json:
$ npx @copilotkit/aimock --config aimock.json --host 0.0.0.0

Fixture Converters

Convert fixtures from other mock tools to aimock format.

Usage

npx @copilotkit/aimock convert <format> <input> [output]

Supported Formats

Examples

# Convert a directory of VidaiMock templates
$ npx @copilotkit/aimock convert vidaimock ./templates/ ./fixtures/converted.json

# Convert a mock-llm YAML config
$ npx @copilotkit/aimock convert mockllm ./config.yaml ./fixtures/converted.json

# Print to stdout (omit output path)
$ npx @copilotkit/aimock convert vidaimock ./templates/

Docker Compose

The published image's ENTRYPOINT runs the flag-driven llmock CLI — it supports -f/--fixtures, -p/--port, -h/--host, and the chaos / record flags, but not --config. Use the compose snippet below for flag-driven fixture serving. For full config-driven mode (LLM + MCP + A2A + AG-UI on one port), either build your own image with @copilotkit/aimock installed, or run npx @copilotkit/aimock --config ... on the host.

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
    depends_on:
      - aimock