system.runtimes

system.runtimes is the bus-side singleton that other actors consult to discover which runtimes exist on this Host. It is owned by the @open-matrix/system package; the Host does not implement it itself. The Host writes to it via the supervised system runtime that mounts system.runtimes.

This page documents how the Host's <home>/runtimes/<id>/runtime.json records relate to the bus actor.

Two views, one source of truth

View	Where	Authoritative?
<home>/runtimes/<id>/runtime.json	filesystem	yes — this is the durable state
system.runtimes actor	NATS bus	no — projection of the above for runtime use

The Host writes the on-disk record first (MatrixHostService.registerRuntimeRecord, matrix-host-service.ts:164-167). The system runtime separately reads its environment and registers itself with system.runtimes at mount-time. host-control heartbeats include the runtime list pulled from on-disk records, not from system.runtimes — the bus actor is for other actors to query.

Who owns the singleton

Per the repo CLAUDE.md § "Architecture: The Four Operational Units", system.runtimes is one of the singleton system mounts. There is one live owner per authority root; multiple processes claiming system.runtimes cause a hard error.

The Host enforces this via mount-conflict checks at matrix-host-service.ts:543-576. Any non-system runtime that tries to include system.runtimes in its localMounts will fail to start with a clear error if another runtime already owns it.

Registry-readiness gate at start

If a starting runtime owns system.runtimes, _waitForRuntimeRegistryReadyIfOwned (matrix-host-service.ts:739-777) blocks until that mount answers $ping. The Host treats system.runtimes as a critical-path mount — auto-starting runtimes that depend on it (host-control, gateway) cannot proceed without it.

What system.runtimes exposes

The actor surface is documented in the @open-matrix/system package, not here. From the Host's perspective the only ops that matter are:

• $ping (used by readiness gate).
• runtime.list / runtime.get (read by other actors needing inventory).

HostControlActor does not call system.runtimes; it reads the on-disk records directly via readRuntimeRecordsFromHome (HostControlActor.ts:536-557). The bus actor exists for other runtimes (e.g. system.devices, matrix-edge) that need a query API without filesystem access.

Heartbeats and system.devices

HostControlActor._registerLocalDeviceHeartbeat (HostControlActor.ts:278-314) iterates the on-disk runtime records and calls system.devices.devices.runtimes.register for each. That populates the Device-facing inventory at system.devices, which is distinct from system.runtimes:

Actor	Audience	Source
system.runtimes	other actors on the bus	the system runtime's in-memory state
system.devices	product UI (Devices page, Edge shell)	host.control heartbeats from each linked Host

Don't conflate them. system.devices is a Device-product facade; system.runtimes is a generic bus registry.

See also

• Host supervisor actor
• Runtime records
• Host vs device
• repo CLAUDE.md § "Architecture: The Four Operational Units"