Configuration mimic.json

The mimic.json file is the single entry point for all of Mimic's behaviour. It lives in your project root and defines what your agent's world looks like — the domain, the people in it, which databases to seed, and how to test the agent.

Created automatically by mimic init, or write one by hand. Only two fields are required: domain and personas. Everything else is optional with sensible defaults.

Minimal example

{
  "domain": "personal finance assistant",
  "personas": [
    {
      "name": "young-professional",
      "description": "28yo product designer, $95K salary, Austin TX"
    }
  ]
}

That’s it. Two fields and you can run mimic run to generate blueprints. Add a databases block when you’re ready to seed real data.

Full example

{
  "domain": "personal finance and banking platform",
​
  "llm": {
    "provider": "anthropic",
    "model": "claude-haiku-4-5"
  },
​
  "personas": [
    {
      "name": "active-trader",
      "description": "31yo software engineer, $140K salary, active stock trader, 5+ bank accounts"
    },
    {
      "name": "saver",
      "description": "27yo teacher, $55K salary, focuses on saving, tracks every dollar"
    }
  ],
​
  "generate": {
    "volume": "6 months",
    "seed": 42
  },
​
  "databases": {
    "postgres": {
      "type": "postgres",
      "url": "$DATABASE_URL",
      "schema": { "source": "introspect" },
      "seedStrategy": "truncate-and-insert"
    },
    "mongodb": {
      "type": "mongodb",
      "url": "$MONGO_URL",
      "database": "mimic_fintech",
      "seedStrategy": "delete-and-insert",
      "autoCreateIndexes": true
    }
  },
​
  "apis": {
    "stripe": { "enabled": true, "mcp": true }
  },
​
  "test": {
    "agent": "http://localhost:3000/chat",
    "scenarios": [
      {
        "name": "balance-check",
        "persona": "active-trader",
        "goal": "Ask about current account balance",
        "expect": {
          "tools_called": ["get_accounts"],
          "response_accurate": true
        }
      }
    ]
  }
}

Field reference

domain

A plain-English description of what your application does. This is the most important field — it’s the primary context given to the LLM when generating persona blueprints. Be specific: “personal finance assistant” generates better data than “app”.

"domain": "e-commerce storefront with product catalog, shopping cart, and order tracking"

Good domain descriptions include the kind of data your app works with. Here are examples from the bundled examples:

• "project and task management app" — generates projects, tasks, labels, comments
• "technical blog and content platform" — generates users, posts, comments, bookmarks
• "e-commerce storefront" — generates customers, products, orders, reviews
• "personal finance and banking platform" — generates accounts, transactions, activity logs

personas

An array of fictional identities that drive data generation. Each persona produces a different style of data — different volumes, different patterns, different values — even though they share the same schema.

"personas": [
  {
    "name": "power-shopper",
    "description": "34yo marketing exec, frequent online buyer, $120K salary, loves electronics and fashion"
  },
  {
    "name": "casual-browser",
    "description": "22yo grad student, occasional buyer, budget-conscious, mostly books and supplies"
  }
]

Each persona generates its own blueprint and seeds its own dataset. When you run mimic seed, every persona’s data is inserted into the same database, giving you a realistic multi-user environment.

llm

Configures which LLM provider and model to use for blueprint generation. If omitted, defaults to Anthropic Claude Haiku.

"llm": {
  "provider": "anthropic",
  "model": "claude-haiku-4-5"
}

The LLM is only called during mimic run (blueprint generation). Once blueprints are generated and cached in .mimic/blueprints/, subsequent mimic seed commands work entirely offline.

generate

Controls the volume and reproducibility of generated data.

"generate": {
  "volume": "6 months",
  "seed": 42,
  "tables": {
    "transactions": 500,
    "users": "auto"
  }
}

The volume field tells the blueprint expander how far back in time to generate data. A “busy-developer” persona with "3 months" might create 40-60 tasks, while "1 year" for the same persona would produce 150-200. The seed makes this deterministic — use it for reproducible test environments and CI pipelines.

databases

A named map of database targets to seed. Each key is a label you choose (e.g. "primary", "analytics", "cache"), and the value configures the connection and seeding behaviour. The type field determines which adapter is used.

Mimic supports four database types: PostgreSQL, MySQL, SQLite, and MongoDB. You can configure multiple databases — even of different types — and mimic seed populates them all in a single command.

PostgreSQL

"primary": {
  "type": "postgres",
  "url": "$DATABASE_URL",
  "schema": {
    "source": "prisma",
    "path": "./prisma/schema.prisma"
  },
  "seedStrategy": "truncate-and-insert"
}

Schema sources tell Mimic how to discover your table structure:

• "prisma" — parses a Prisma schema file with prisma-ast. Supports enums, relations, and column-level annotations
• "sql" — parses SQL DDL files (CREATE TABLE statements)
• "introspect" — connects to the live database and reads information_schema. No schema files needed, but requires the database to be running with tables already created

MySQL

"primary": {
  "type": "mysql",
  "url": "$DATABASE_URL",
  "schema": { "source": "introspect" },
  "seedStrategy": "truncate-and-insert"
}

SQLite

"local": {
  "type": "sqlite",
  "path": "./tasks.db",
  "walMode": true,
  "seedStrategy": "truncate-and-insert"
}

SQLite requires no server — the database is a single file. Use "walMode": true if your agent reads the database while Mimic is seeding, to avoid locking issues.

MongoDB

"documents": {
  "type": "mongodb",
  "url": "$MONGO_URL",
  "database": "mimic_blog",
  "seedStrategy": "delete-and-insert",
  "autoCreateIndexes": true
}

MongoDB does not require a schema file. Mimic generates document shapes from the domain description and persona, making it the fastest database to get started with. Set "autoCreateIndexes": true to automatically index common query fields.

Schema source availability

Seed strategies

apis

A named map of API mock adapters. Each key is the adapter ID (e.g. "stripe", "plaid", "paddle"), and the value configures the adapter’s behaviour. When mimic host runs, enabled adapters are registered as Fastify routes on the mock server. When mcp: true, the adapter’s tools are also registered on the unified MCP server.

"apis": {
  "stripe": { "enabled": true, "mcp": true },
  "plaid": { "enabled": true, "mcp": true }
}

Use mimic adapters add stripe to install and configure an adapter, or add the entry to mimic.json by hand.

test

Defines test scenarios that mimic test runs against your agent. Each scenario sends a goal to the agent and verifies the response against expected outcomes — which tools were called, whether the response contains expected keywords, and whether the response is factually accurate.

"test": {
  "agent": "http://localhost:3000/chat",
  "mode": "text",
  "evaluator": "both",
  "scenarios": [
    {
      "name": "monthly-spending",
      "persona": "young-professional",
      "goal": "Ask about total spending last month",
      "expect": {
        "tools_called": ["get_transactions"],
        "response_contains": ["spending", "total"],
        "response_accurate": true,
        "no_hallucination": true,
        "max_latency_ms": 5000
      }
    }
  ]
}

Auto-scenario generation

When auto_scenarios is true, mimic test reads the fact manifest (.mimic/fact-manifest.json, written by mimic run) and generates test scenarios via an LLM call. Each fact in the manifest becomes a scenario with a natural-language question and specific assertions grounded in the generated data. Use scenario_tiers to limit which tiers are generated, and export to set a default export format. See Testing & Auto-Scenarios for the full guide.

"test": {
  "agent": "http://localhost:3000/chat",
  "auto_scenarios": true,
  "scenario_tiers": ["smoke", "functional"],
  "export": "promptfoo",
  "scenarios": []
}

Scenario fields

Expectation fields

Environment Variables

Any string value in mimic.json can reference an environment variable using the $VARIABLE_NAME syntax. Variables are resolved at config load time.

// In mimic.json:
"url": "$DATABASE_URL"
​
// Resolved from your shell:
// export DATABASE_URL="postgresql://user:pass@localhost:5432/mydb"

Common environment variables used across examples: