Runtime Host

Appearance

Host status schema ​

<host-home>/host.status.json is the live status of the Host process. Schema is IHostStatus at projects/matrix-3/packages/host-service/src/types.ts:121-156.

ts
export interface IHostStatus {
  readonly kind: 'MatrixHostStatus';
  readonly version: 1;
  readonly status: 'starting' | 'running' | 'stopping' | 'stopped';
  readonly pid: number;
  readonly home: string;
  readonly root: string;
  readonly authorityRoot: string;
  readonly addressRoot: string;
  readonly supervisorMount?: string;
  readonly startedAt: string;
  readonly updatedAt: string;
  readonly http: {
    readonly host: string;
    readonly port: number;
    readonly origin: string;
  };
  readonly transport: {
    readonly authorityRoot?: string;
    readonly addressRoot?: string;
    readonly spaceId?: string;
    readonly routeKey?: string;
    readonly publicNamespace?: string;
    readonly root: string;            // legacy alias of authorityRoot
    readonly nats: {
      readonly mode: 'embedded' | 'external';
      readonly url: string;
      readonly wsUrl?: string;
      readonly credentialsRef?: string;
    };
  };
}

Lifecycle ​

  • Written by MatrixHostService.start() once everything is up (matrix-host-service.ts:99-103).
  • Atomically rewritten on every config reload, every supervisor shutdown, and inside applyUpdatedHostConfig.
  • Removed by MatrixHostService.stop() and by clearStatus whenever a stale status is detected via dead pid (host-state-store.ts:84-88 and matrix-host-service.ts:130-133).

The presence of host.status.json is the canonical "Host is running" signal. Its absence (or a present file pointing at a dead pid) means the Host is not running.

Field reference ​

Kind and version ​

json
"kind": "MatrixHostStatus",
"version": 1

Both fixed. Version is reserved for future schema breaks; no break has happened yet.

status ​

One of "starting", "running", "stopping", "stopped". Live states are starting/running/stopping (isLiveStatus, host-state-store.ts:1207-1209). A persistent "stopped" on disk indicates the Host crashed mid-stop and should be cleared.

pid ​

The Host process pid. Validators (isProcessAlive, host-state-store.ts:130-134) check this is alive on read; a dead pid causes host.status.json to be removed and null returned.

home ​

Absolute path to <host-home>. Equals MATRIX_HOST_HOME / config.home.

root, authorityRoot, addressRoot ​

Three views of the same prefix string:

  • authorityRoot — the bus authority root, derived from host.jsontransport.authorityRoot or transport.root.
  • root — legacy alias of authorityRoot. New callers should use authorityRoot.
  • addressRoot — the public address root advertised to bootstrap and browser clients. Defaults to authorityRoot unless overridden.

supervisorMount ​

host.supervisor.PID-<pid>. The mailbox subject for the host-supervisor RPC, with the pid suffix to prevent two Host processes claiming the same subject. Built at matrix-host-service.ts:935.

startedAt, updatedAt ​

ISO8601 strings. startedAt is set once on start() and persists. updatedAt is bumped on every write.

http ​

json
"http": {
  "host": "127.0.0.1",
  "port": 3100,
  "origin": "http://127.0.0.1:3100"
}

The gateway HTTP runtime's bind. origin is the canonical URL the gateway will serve from. Used by browsers, by curl /healthz, and by the supervisor's view of "where to send asset requests."

If host.json http.port was null, this field shows the OS-allocated port chosen at start.

transport ​

The full transport config snapshot:

json
"transport": {
  "root": "COM.OPEN-MATRIX.LOCAL.AUTHORITY",
  "authorityRoot": "COM.OPEN-MATRIX.LOCAL.AUTHORITY",
  "addressRoot": "COM.OPEN-MATRIX.LOCAL.AUTHORITY",
  "nats": {
    "mode": "external",
    "url": "nats://127.0.0.1:4222",
    "wsUrl": "ws://127.0.0.1:4223"
  }
}

Optional fields appear only when populated:

  • spaceId — set by system-auth after Device pairing.
  • routeKey — v1 alias for the public Space path.
  • publicNamespace — space.<spacePath>, derived during pairing.
  • nats.credentialsRef — set when the Host's NATS access requires credentials (e.g. the cloud Host).

Full example ​

json
{
  "kind": "MatrixHostStatus",
  "version": 1,
  "status": "running",
  "pid": 12345,
  "home": "/var/lib/hivecast",
  "root": "COM.OPEN-MATRIX.LOCAL.AUTHORITY",
  "authorityRoot": "COM.OPEN-MATRIX.LOCAL.AUTHORITY",
  "addressRoot": "COM.OPEN-MATRIX.LOCAL.AUTHORITY",
  "supervisorMount": "host.supervisor.PID-12345",
  "startedAt": "2026-05-04T18:00:01.000Z",
  "updatedAt": "2026-05-04T18:00:02.103Z",
  "http": { "host": "127.0.0.1", "port": 3100, "origin": "http://127.0.0.1:3100" },
  "transport": {
    "root": "COM.OPEN-MATRIX.LOCAL.AUTHORITY",
    "authorityRoot": "COM.OPEN-MATRIX.LOCAL.AUTHORITY",
    "addressRoot": "COM.OPEN-MATRIX.LOCAL.AUTHORITY",
    "nats": {
      "mode": "external",
      "url": "nats://127.0.0.1:4222",
      "wsUrl": "ws://127.0.0.1:4223"
    }
  }
}

For a Host that has been Device-Linked to HiveCast, the transport block additionally carries spaceId, routeKey, and publicNamespace.

Reading it ​

bash
jq . <home>/host.status.json
hivecast status --home <home> | jq .         # combined with runtime list

The CLI's status command (cli.ts:53-75) reads this file, then enriches it with a host.control.status RPC call.

See also ​