Persistence

Technical detailsCopy Anchor Link

Where snapshots liveCopy Anchor Link

Snapshots live under $MIRAVO_HOME/state/. The default base directory is ~/.miravo. The file name is the factory name, so my-sim above is a factory started with --name my-sim.

What is restoredCopy Anchor Link

Miravo persists the templates loaded into the factory, and the assets with their IDs and browse paths, parameters, operating hours, lifecycle stage, active faults, input bindings, protocol scope, owning template, and the enabled adapter configuration. Adapter configuration is saved through an allow-list: only the documented non-secret settings of the built-in MQTT, OPC UA, and Modbus adapters (ports, hosts, tuning, reconnect and RBE options) are written, and a custom adapter saves no configuration at all. The MQTT username and password are never written, and an external broker URL is saved as scheme, host, and path only (no credentials, query, or fragment); Miravo records which of these were removed. On restore they come from the current environment (MIRAVO_MQTT_USERNAME, MIRAVO_MQTT_PASSWORD, MIRAVO_MQTT_URL) or template, and the broker URL is used only when its scheme, host, and path match the saved one. A saved external broker always needs that boot URL, and when the saved URL carried credentials the boot URL must carry credentials too. Miravo refuses to enable an adapter whose saved secret or broker URL is missing, or whose broker differs, with a warning naming it; the adapter stays enabled in the snapshot, so it comes back once you provide the setting and restart, unless you disable it explicitly, which saves it as disabled. A state file that lists the same adapter twice is rejected and moved aside. It does not persist current member values, in-flight protocol traffic, or the exact position of the random number stream.

The snapshot stores the factory name as factoryName, the loaded templates as templates (id, name, entry file path, and a hash of the entry file), and the asset records as assets. Each asset names its template with templateId; assets spawned on their own have none.

Miravo writes a snapshot after startup reconciliation and before the first tick. Later writes are debounced and serialized so they cannot race. Loading a template, unloading one, or running miravo reset updates the snapshot too.

What happens on restartCopy Anchor Link

Every saved template reloads from its entry file. Miravo then decides per template:

• Unchanged (same path, same hash): its saved state is restored.
• Changed (the file was edited): the template loads fresh from the file, and its saved state is dropped.
• Missing (the file is gone): the template is dropped.

A template you pass with -t that is not in the snapshot is added fresh. -t a,b and templates loaded at runtime with miravo load survive a restart the same way. Standalone assets restore as saved. If a -t template defines an asset ID that a saved standalone asset or a different saved template owns, the -t template is not loaded and a warning names the ID; the saved state wins. miravo reset empties the factory and saves that, so the next start comes up empty. If the save fails, the reset reports the error and the old snapshot stays. A factory started with --template none neither loads nor saves a snapshot, so resetting it leaves any saved snapshot of that name as is.

The hash covers the whole entry file, byte for byte. Any edit counts as a change, including a comment or whitespace change. Models and other files the template references are not part of the hash.

A template read from stdin (miravo load -t -) is stored as a temporary file that Miravo removes afterwards, so it cannot reload and is reported as not found on the next start. Save it to a file and load that instead.

With no -t, miravo start uses the bundle in the current directory, or shows the template picker. Saved state never picks the template; it is restored once the factory boots.

miravo start prints one line for each outcome, also in the start -d summary:

Restored saved state: 8 assets (from <path>). Start fresh with --fresh.
Saved state discarded for template 'smart-factory': template file changed since it was saved. Loaded fresh.
Saved state discarded for template 'smart-factory': template file not found at <path>.

A snapshot that is not valid JSON, has an unexpected version, or fails schema validation is renamed to <factory>.json.corrupt, and Miravo starts fresh. This includes snapshots written by older versions.

Start fresh or clear saved stateCopy Anchor Link

miravo start --fresh

miravo reset

ReferenceCopy Anchor Link

Related pagesCopy Anchor Link