Runtime record schema

The schema is IHostRuntimeRecord at projects/matrix-3/packages/host-service/src/types.ts:79-96.

export interface IHostRuntimeRecord {
  readonly runtimeId: string;
  readonly packageRef?: string;
  readonly packageDir?: string;
  readonly environment?: string;
  readonly pid?: number;
  readonly status: 'starting' | 'running' | 'stopping' | 'stopped' | 'failed';
  readonly startup?: 'manual' | 'auto';
  readonly restart?: 'never' | 'always' | 'on-failure';
  readonly startedAt?: string;
  readonly stoppedAt?: string;
  readonly updatedAt: string;
  readonly runtimeMount?: string;
  readonly controlMount?: string;
  readonly runtimeWireRoot?: string;
  readonly localMounts: readonly string[];
  readonly metadata: Record<string, unknown>;
}

The on-disk representation is exactly this JSON, atomically written. There is no version field — the schema is additive-only and unknown fields are ignored on read.

Required fields

Field	Type	Notes
`runtimeId`	string	sanitized to `^[A-Za-z0-9_-]+$`. The directory name and this field must match.
`status`	enum	one of the five states; see Runtime status
`updatedAt`	ISO8601 string	bumped on every state change
`localMounts`	string[]	logical mounts the runtime claims; checked for conflict at start
`metadata`	object	free-form; the Host adds standard keys (see below)

The validator (isHostRuntimeRecord, host-state-store.ts:240-249) only checks shape on these five fields. A record missing metadata (object) or with a non-string runtimeId is treated as corrupt: { reason: "shape" }.

Optional fields

Lifecycle

Field	Use
`pid`	OS process pid; required for live status records (`runtime`/`stopping`/`starting`); checked for liveness on every read
`startedAt`	first successful spawn (ISO8601)
`stoppedAt`	when the runtime exited (ISO8601)
`startup`	`"manual"` (default) or `"auto"` — whether to launch at Host start
`restart`	`"never"` (default), `"always"`, `"on-failure"` — see Restart runtime

Identity

Field	Use
`packageRef`	package name (e.g. `@open-matrix/chat`) — for diagnostics and stop-target matching
`packageDir`	absolute path to the package directory; required for auto-restart
`environment`	env name from `--env <name>`; written into the env file
`runtimeWireRoot`	the NATS subject root the runtime uses; required (`runtimeWireRootForRecord`, `matrix-host-service.ts:1314-1320`)
`runtimeMount`	logical mount that other actors call into
`controlMount`	mount the supervisor calls for `runtime.ready`, `runtime.health`, `runtime.shutdown`

`metadata` keys the Host adds

MatrixHostService.startRuntimeProcess (matrix-host-service.ts:404-429) writes these:

Key	Type	Purpose
`command`	string	absolute path to the runtime's spawn binary
`args`	string[]	argv after `command`
`cwd`	string	working directory for the spawn
`env`	object	per-runtime env-var overlay
`controlReadyTimeoutMs`	number	readiness deadline used at next start
`logDir`	string	absolute path to per-runtime log directory
`source`	string	`"matrix-cli"` for human-driven starts
`target`	string	original `--target` argument (e.g. `@open-matrix/chat`)
`envFile`	string	absolute path to the runtime-env JSON
`transport`	object	snapshot of `host.status.json` `transport` at start time
`autoStartPriority`	number	persisted from `--auto-start-priority`
`autoStartReason`	string	`"host-autostart"`, `"runtime-exit"`, or operator-supplied
`autoStartOrdinal`	number	which slot in the auto-start sweep this runtime took
`webapp`	object	`{ appName, routePrefix, port, origin, ... }` for served apps
`serve`	true	only present when `--serve` was used

On failure, the Host adds:

Key	Purpose
`failedReason`	error message, including a tail of stderr/stdout
`staleDetectedAt`, `staleReason`	for stale records
`exitCode`, `signal`	from the `child.exit` event
`restartFailedAt`, `restartFailedReason`, `restartReason`	for failed restarts
`orphanRecoveredAt`, `orphanRecoveredPid`, `orphanRecoveryOutcome`, `orphanRecoveryReason`	for orphan-recovery transitions

On health refresh, the Host adds:

Key	Purpose
`controlHealthCheckedAt`, `controlHealthStatus`, `controlHealthReason`	recent `runtime.health` outcome
`envFileRefreshedAt`, `envFileRefreshReason`	last env-file rewrite
`envFileObservedAt`, `envFileObservedReason`	last lazy alignment

Full example

json

{
  "runtimeId": "RUNTIME-HOST-LOCAL-A1B2C3D4-CHAT",
  "packageRef": "@open-matrix/chat",
  "packageDir": "/var/lib/hivecast/packages/system/node_modules/@open-matrix/chat",
  "environment": "host",
  "pid": 41522,
  "status": "running",
  "startup": "auto",
  "restart": "always",
  "startedAt": "2026-05-04T18:21:01.103Z",
  "updatedAt": "2026-05-04T18:21:02.991Z",
  "runtimeMount": "system.runtimes.RUNTIME-HOST-LOCAL-A1B2C3D4-CHAT",
  "controlMount": "system.runtimes.RUNTIME-HOST-LOCAL-A1B2C3D4-CHAT.control",
  "runtimeWireRoot": "COM.OPEN-MATRIX.LOCAL.AUTHORITY",
  "localMounts": [
    "chat",
    "system.runtimes.RUNTIME-HOST-LOCAL-A1B2C3D4-CHAT",
    "system.runtimes.RUNTIME-HOST-LOCAL-A1B2C3D4-CHAT.control"
  ],
  "metadata": {
    "source": "matrix-cli",
    "target": "@open-matrix/chat",
    "envFile": "/var/lib/hivecast/runtime-env/RUNTIME-HOST-LOCAL-A1B2C3D4-CHAT.environment.json",
    "command": "/opt/hivecast/node/bin/node",
    "args": ["/opt/hivecast/dist/node_modules/@matrix/mx-cli/dist/index.cjs", "run", "/var/lib/hivecast/.../chat", "--serve", "--env", "host", "--env-file", "/var/lib/hivecast/runtime-env/...environment.json"],
    "cwd": "/var/lib/hivecast/packages/system/node_modules/@open-matrix/chat",
    "logDir": "/var/lib/hivecast/logs/runtimes/RUNTIME-HOST-LOCAL-A1B2C3D4-CHAT",
    "controlReadyTimeoutMs": 30000,
    "transport": {
      "root": "COM.OPEN-MATRIX.LOCAL.AUTHORITY",
      "nats": { "mode": "embedded", "url": "nats://127.0.0.1:4222", "wsUrl": "ws://127.0.0.1:4223" }
    },
    "autoStartPriority": 25,
    "autoStartReason": "host-autostart",
    "autoStartOrdinal": 6,
    "serve": true,
    "webapp": {
      "appName": "chat",
      "routePrefix": "/apps/chat/",
      "port": 5183,
      "origin": "http://127.0.0.1:5183"
    }
  }
}

What the Host re-derives at start

runtimeWireRoot always rewritten from the live transport root.
metadata.transport always rewritten.
metadata.envFileRefreshedAt, envFileRefreshReason rewritten.
metadata.webapp.origin, metadata.webapp.port realigned with the runtime's environment file http.port.

Other fields persist as written. If you edited a record by hand and restart the Host, your command, args, cwd, localMounts, startup, restart, metadata.autoStartPriority survive.

Runtime record schema ​

Required fields ​

Optional fields ​

Lifecycle ​

Identity ​

metadata keys the Host adds ​

Full example ​

What the Host re-derives at start ​

See also ​