Running Mocko

Persistence and Redis

Every persistence question in Mocko has the same answer: are you running storeless or with Redis? This page is the definitive breakdown of the two modes, what each one stores, and when to switch.

The two modes

Storeless is the default. Everything created at runtime lives in the process memory and disappears when Mocko stops. No dependencies, instant startup, and every session begins in a known clean state, which is exactly what you want on a laptop and in CI.

Redis mode moves that runtime state into Redis. Mocks created in the UI, hosts, and flags survive restarts, several core replicas stay consistent, and the management operations become available. This is the mode for shared instances.

What lives where

File mocks, hosts, and data blocks from .hcl files: always come from your files, in both modes. Their durability is your git history; a restart simply reloads them.
Deployed mocks and hosts (created in the UI): memory in storeless mode, Redis in Redis mode.
Flags: same split. In storeless mode a restart resets all state your mocks accumulated; in Redis mode a simulated scenario picks up where it left off.

This split is why the recommended workflow keeps repeatable behavior in files and treats the UI as an override layer: the part that matters is versioned regardless of mode, and the runtime layer is durable exactly when you choose it to be.

Enabling Redis in each run mode

On the CLI, pass a Redis URL:

mocko -r redis://localhost:6379 --watch mocks

In containers (Compose or the split images), set the environment variables:

REDIS_ENABLED: "true"
REDIS_URL: redis://redis:6379
# or discrete settings: REDIS_HOST, REDIS_PORT, REDIS_PASSWORD, REDIS_DATABASE

On Kubernetes with Helm, persistence is on by default with a chart-managed Redis, and persistence.redis.* switches it to an external one.

When to switch to Redis

A shared instance where the team manages mocks through the UI and expects them to still be there tomorrow.
More than one core replica: without a shared store, each replica would have its own flags and deployed mocks, and behavior would depend on which pod answered.
Long-lived stateful simulations, like the Stateful CRUD recipe backing a QA environment for weeks.
The management operations for cleaning up and inspecting flags at scale, which are Redis-only.

Conversely, stay storeless while the reset-on-restart behavior is doing you a favor: local development and CI runs usually want a clean slate, not durability.

Sharing a Redis instance

Mocko namespaces every key under a prefix, mocko: by default, configurable via REDIS_PREFIX (or persistence.redis.prefix in Helm). Give each Mocko deployment its own prefix when several share one Redis, or when Mocko shares a Redis with other applications.

Behavior details

Flag TTLs work in both modes; in Redis mode they map to real key expirations, so expired scenario state cleans itself up.
Redis mode does not change how file mocks load. Files are still read from disk on startup and on watch reloads, never from Redis.

That wraps the run modes. For the complete list of environment variables behind them, head to the configuration reference.