Custom Content

Create custom models and templates by forking built-in content or writing from scratch.

Content Resolution

Miravo resolves models and templates through three layers in priority order:

1. Current directory — .twin.yaml and .miravo.yaml files in the working directory
2. Local registry — ~/.miravo/registry/local/{models,templates}/
3. Built-in — Shipped with Miravo via the @miravo/content package

A model in the current directory overrides the same name in the local registry, which overrides built-in content.

Fork Built-in Content

The miravo fork command copies built-in content to the local registry for customization.

Fork a Model

miravo fork model centrifugal-pump

Creates ~/.miravo/registry/local/models/centrifugal-pump.twin.yaml. Edit this file to customize parameters, members, generators, faults, or lifecycle.

Fork a Template and Its Models

miravo fork template smart-factory

Copies the template and all referenced models to the local registry.

Fork Models Only

miravo fork template smart-factory --models-only

Copies only the models referenced by the template, not the template file itself.

Overwrite Existing

By default, fork skips files that already exist. Use --force to overwrite:

miravo fork model centrifugal-pump --force

Write From Scratch

Custom Model

Create a .twin.yaml file in your working directory or local registry:

schema_version: "2"
model:
  name: my-sensor
  description: "Custom temperature/humidity sensor"

parameters:
  temp_center:
    type: float
    default: 22.0
    unit: degC

members:
  temperature:
    kind: variable
    data_type: Double
    access: read
    unit: degC
    generator:
      type: noise
      center: "$param.temp_center"
      stddev: 0.3

  humidity:
    kind: variable
    data_type: Double
    access: read
    unit: "%RH"
    generator:
      type: mean-reverting-noise
      mean: 45
      tau: 20
      sigma: 2

Custom Template

Create a .miravo.yaml file:

kind: MiravoTemplate
version: "1"
name: "My Custom Plant"
description: "Custom sensor array"

namespace:
  enterprise: MyCompany
  site: test-lab

areas:
  - name: floor-1
    lines:
      - name: zone-a
        twins:
          - model: my-sensor
            count: 10
            variation: 0.1

settings:
  tick_interval_ms: 1000
  time_multiplier: 1

Run it:

miravo start --template ./my-plant.miravo.yaml

Local Registry Structure

~/.miravo/
  registry/
    local/
      models/          # Custom .twin.yaml files
      templates/       # Custom .miravo.yaml files
  state/               # Persisted simulation snapshots
  daemon/              # Background process registry

The base directory is configurable with MIRAVO_HOME:

MIRAVO_HOME=/data/miravo miravo start

Validate Without Running

Use --dry-run to validate a template and its referenced models without starting the simulation:

miravo start --template ./my-plant.miravo.yaml --dry-run

This catches schema errors, missing models, invalid parameter references, and member ordering issues.