Hot Reload

Mimic rescans the mocks directory every 2 seconds and reflects file changes without a restart. You can edit, add, or delete a mock file and the next request will use the new state — no container restart, no rebuild.

What triggers a reload

Editing a file — saving changes to an existing mock updates that endpoint.
Adding a file — a new mock file becomes a new route.
Deleting a file — the route disappears and subsequent requests get 404.
Renaming a file — equivalent to deleting one and adding another.
Editing a response_file fixture — picked up even when the mock file that references it isn’t touched.

Try it

With Mimic running and mocks/get_users.json in place from the Quick Start:

curl http://localhost:8080/users

Now edit mocks/get_users.json, change one of the names, save, and curl again:

curl http://localhost:8080/users

The new name appears in the response within about 2 seconds.

How it works under the hood

Change detection is a dependency-free stat-based check, not OS-level filesystem-event watching (inotify or similar). Each mock file — and each response_file it references — is fingerprinted by modified time and size:

A cycle where nothing changed does no file I/O. Unchanged files are neither re-read nor re-parsed, and the mock store’s write lock isn’t even taken.
Cost is at most one stat per file per idle cycle, with no OS-specific watch API — so it degrades the same way on every platform and every filesystem, including inside a container with a bind-mounted mocks directory, where inotify events don’t always cross the mount.
A symlink that resolves back into the mocks tree — directly, or through a shared-fixtures setup in a monorepo — is walked once and reported, rather than registering its mocks over and over on every cycle.

The trade-off is a reload triggered by a stat sweep rather than an instantaneous filesystem event — invisible at the 2-second cadence Mimic already reloads on.

Failures are isolated per file

If one file has invalid JSON/YAML — an editor mid-save, a teammate’s work-in-progress in a shared mocks directory — every other file in that cycle still applies. A single typo can no longer block unrelated mock changes from taking effect.

The broken file’s own route isn’t dropped either — it keeps serving its last successfully-loaded response until the file parses again, so routes don’t flap in and out of existence while somebody is editing. Each failure is logged with the file name and parse error, plus a summary of how many endpoints were applied and how many were carried forward.

Deletions still take effect normally: on a clean cycle (no parse errors) the mock set is replaced outright, so removing a file removes its route.

What happens to sequence state across a reload

Sequence positions and hit counts belong to the mock’s file, not to its position in the list of mocks sharing a METHOD:path. Across a reload:

Editing a file — including editing its sequence — leaves that mock’s position and hit count where they were. Reset explicitly with POST /admin/sequences/reset when you want a clean run.
Adding a mock under a METHOD:path that already has one does not disturb the existing mock’s counters, whichever order the two files sort in.
Deleting a file drops its counters. They are not carried over to whatever is loaded next.
A file that stops parsing keeps both its route and its counters, since its last-known-good response is still being served.

When hot reload might not work

Invalid JSON/YAML. If your edit produces a malformed file, Mimic logs an error and keeps the previous version of that mock active until you fix it. Check the logs with docker logs mimic.
A change made and reverted within the same 2-second window may never trigger a cycle at all, since the fingerprint (modified time and size) ends up unchanged. This is rarely visible in practice.

Disabling hot reload

There is no flag to disable hot reload — it’s always on. If you don’t want it (for example in CI, where the mocks folder won’t change), the idle-cycle cost is small enough that there’s no reason to turn it off.