Persistence

Miravo persists simulation state to disk so restarts resume where they left off.

How It Works

State is saved as a JSON snapshot at ~/.miravo/state/{simulationName}.json (or $MIRAVO_HOME/state/). The snapshot captures:

• All active instances with their IDs, browse paths, and parameters
• Operating hours and lifecycle stage per instance
• Active faults per instance
• Template run assignments
• Enabled adapters and their configuration

Automatic Save

Miravo debounces structural changes and writes a snapshot when:

• Instances are spawned or removed
• Templates are loaded or unloaded
• Adapters are enabled or disabled
• The simulation stops gracefully

A boot snapshot is written immediately after startup reconciliation, before the first tick.

Restore on Startup

When a simulation starts with a name that matches an existing snapshot:

1. The snapshot is validated with Zod schemas
2. Preloaded boot instances are cleared
3. Instances are restored with their exact IDs, operating hours, lifecycle stages, and active faults
4. Template run assignments are restored
5. Enabled adapters are re-enabled with their persisted configuration
6. Spawn counters advance past restored numeric IDs to avoid collisions

The snapshot is authoritative — it replaces any boot-time configuration.

Clearing State

Remove persisted state with the reset command:

Reset simulation (remove all instances, keep persistence):

miravo reset

Reset simulation and clear persisted state:

miravo reset --clear-persistence

Or via the admin API:

curl -s http://127.0.0.1:8080/commands \
  -H 'content-type: application/json' \
  -d '{"type":"resetSimulation","clearPersistence":true}'

Persistence Location

Config	Default	Description
MIRAVO_HOME	~/.miravo	Base directory
—	$MIRAVO_HOME/state/	Snapshot directory

In Docker, mount a volume to preserve state across container restarts:

volumes:
  - ./miravo-data:/data/miravo
environment:
  MIRAVO_HOME: /data/miravo

What Is Not Persisted

• Current member values (regenerated from generators on each tick)
• RNG state (seeded RNG is deterministic from the seed, but exact sequence position is not saved)
• In-flight MQTT messages or OPC UA subscriptions