system.runtimes

system.runtimes is the physical runtime inventory owned by @open-matrix/host-service. Director reads it; it never writes to it (lifecycle ops belong to host.control and mx-cli).

Ops Director consumes

`runtimes.registered` (read)

DirectorRuntimeAdapter.listRuntimes (src/services/DirectorRuntimeAdapter.ts:209-225):

const result = await RequestReply.execute(
  context,
  'system.runtimes',
  'runtimes.registered',
  {},
  { timeoutMs: 5000, targetRoot: root },
) as { ok?: boolean; runtimes?: IDirectorRuntimeEntry[] };
return Array.isArray(result?.runtimes) ? result.runtimes : [];

Failures are swallowed and treated as "no runtimes registered". The empty path is the same as the unhealthy path; the UI surfaces this as the "no live runtime attached" topology label and an empty tree.

Subscriptions

DirectorApp.subscribes (src/DirectorApp.ts:108-112) declares:

'system.runtimes/$events': {
  filter: ['runtimes.added', 'runtimes.removed', 'runtimes.inventory.changed'],
  description: 'Live runtime presence changes — patch the runtime inventory branch',
}

When any of those events fire, DirectorApp rebuilds the catalog (re-issuing runtimes.registered and registry.list) and patches the tree. There is no incremental delta application; the redraw is whole-tree.

Runtime entry shape

IDirectorRuntimeEntry (src/types.ts:20-37):

{
  runtimeId: string,             // e.g. "RUNTIME-HOST-...-CHAT"
  type: string,                  // 'package-runtime' | 'host-control' | 'system' | ...
  app: string,                   // appName from manifest, e.g. 'chat', 'director'
  sessionMount: string,          // wire root, e.g. 'COM.NIMBLETEC.RICHARD-SANTOMAURO/RUNTIME-...'
  actorCount: number,
  registeredAt: number,
  lastHeartbeat: number,
  uptimeMs?: number,
  claims?: Array<{ prefix: string; kind: string }>,
  inventoryMode?: 'embedded' | 'pull' | 'unknown',
  inventory?: Array<{
    mount: string,
    type?: string,
    surface?: string,
    runtimeId: string,
    claimKind: string,
    description?: string,
    hasChildren?: boolean,
  }>,
  catalogMount?: string,
  controlMount?: string,
  heartbeatTtlMs?: number,
  metadata?: Record<string, unknown>,
}

inventory[] is what makes a runtime a "fat" record. With inventoryMode: 'embedded', the runtime advertises every actor mount + type + description in the heartbeat itself — Director uses that to enrich registry-only entries (buildCatalogFromBindings line 472-491).

Direct CLI for the same data

bash

matrix invoke system.runtimes runtimes.registered '{}'

Same response, no Director needed. Useful in shell debugging.

Why Director does not write

Lifecycle (runtimes.start, runtimes.stop, runtimes.register, runtimes.deregister) belongs to host.control. Mounting these ops in Director would let a browser tab restart your supervisor — a category mistake. The WORKSTREAMS/docker-npm-parity/ track is explicit that system.runtimes is read-only for everyone except host.control.

system.runtimes ​

Ops Director consumes ​

runtimes.registered (read) ​

Subscriptions ​

Runtime entry shape ​

Direct CLI for the same data ​

Why Director does not write ​

See also ​