Admin API

The admin HTTP server runs alongside every Miravo simulation. Default bind: http://127.0.0.1:8080.

Endpoints

Method	Path	Purpose
GET	/healthz	Liveness check
GET	/readyz	Readiness check (engine + adapters)
GET	/metrics	Engine metrics snapshot
GET	/state	Engine state snapshot
POST	/commands	Execute an engine command
POST	/shutdown	Graceful shutdown (daemon mode)
GET	/instances/:id	Full detail for one instance
GET	/models/:name	Model schema
GET	/events	Paginated event log
GET	/ws	WebSocket upgrade for real-time streaming

Health Checks

GET /healthz

Returns 200 when the engine is running and the tick loop is progressing. Returns 503 when stopped or stalled.

curl -s http://127.0.0.1:8080/healthz | jq .

GET /readyz

Returns 200 when the engine is running and all enabled adapters are connected. Returns 503 if any adapter is disconnected or the engine is paused/stopped.

State and Metrics

GET /state

Structural snapshot with models, instances, configuration, and available adapters.

curl -s http://127.0.0.1:8080/state | jq .

GET /metrics

Runtime metrics including tick count, instance count, and per-adapter statistics.

GET /instances/:id

Full detail for a single instance: member values, parameters, methods, lifecycle, faults.

curl -s http://127.0.0.1:8080/instances/pump-001 | jq .

GET /models/:name

Model schema with parameters, members, methods, faults, and lifecycle definition.

curl -s http://127.0.0.1:8080/models/centrifugal-pump | jq .

Commands

POST /commands

Execute an engine command. Accepts a JSON command object — see supported command types below.

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

Supported command types:

Command	Key fields
pause	—
resume	—
setSpeed	multiplier
spawn	model, count, variation, parameterOverrides
removeInstance	instanceId
setParameter	instanceId, parameter, value
triggerFault	instanceId, fault
clearFault	instanceId, fault
unquarantine	instanceId
invokeMethod	instanceId, method, arguments
loadTemplate	templatePath, count
unloadTemplateRun	templateRunId
resetSimulation	clearPersistence
enableAdapter	adapter, config
disableAdapter	adapter

Example — invoke a model method:

curl -s http://127.0.0.1:8080/commands \
  -H 'content-type: application/json' \
  -d '{
    "type": "invokeMethod",
    "instanceId": "pump-001",
    "method": "SetSpeed",
    "arguments": {"speed_rpm": 900}
  }'

Event Log

GET /events

Paginated event log with cursor-based pagination.

Fetch recent fault events:

curl -s 'http://127.0.0.1:8080/events?type=fault:triggered&limit=10'

Query parameters:

Param	Description
type	Filter: fault:triggered, fault:cleared, lifecycle:changed, instance:created, instance:removed, engine:state-changed
instanceId	Filter by instance
limit	Page size (default 100, max 1000)
cursor	Cursor for backward pagination

Response: { "events", "nextCursor", "total" }

WebSocket

GET /ws

Upgrade to WebSocket for real-time event streaming.

websocat ws://127.0.0.1:8080/ws

On connect, the server sends a snapshot message with current state. Then it pushes events on subscribed channels.

Channels: tick, faults, lifecycle, instances, engine, adapters (all enabled by default).

Change subscriptions:

{"type": "subscribe", "channels": ["faults", "lifecycle"]}

Max 10 concurrent WebSocket connections. Messages carry monotonic revision numbers for ordering.

Authentication

Set MIRAVO_ADMIN_TOKEN to require bearer token auth on mutation endpoints:

export MIRAVO_ADMIN_TOKEN=my-secret-token

Commands now require the token:

curl -s http://127.0.0.1:8080/commands \
  -H 'content-type: application/json' \
  -H 'Authorization: Bearer my-secret-token' \
  -d '{"type":"pause"}'

Read-only endpoints (/healthz, /readyz, /metrics, /state, /instances/*, /models/*, /events) do not require auth.

When binding to a non-loopback address, MIRAVO_ADMIN_TOKEN is required for mutation endpoints. Without it, POST /commands and POST /shutdown return 403.

Configuration

Option	Env Var	Default	Description
--admin-port	MIRAVO_ADMIN_PORT	8080	Admin server port
--admin-host	MIRAVO_ADMIN_HOST	127.0.0.1	Admin server bind host
—	MIRAVO_ADMIN_TOKEN	—	Bearer token for mutation endpoints