Runtime instances

A runtime instance on a Host is described by a single <host-home>/runtimes/<runtimeId>.json file. The shape is IHostRuntimeRecord from packages/host-service/src/types.ts:81-97. This page walks every field.

On-disk layout

<host-home>/
├── runtimes/
│   ├── RUNTIME-HOST-SYSTEM.json
│   ├── RUNTIME-HOST-GATEWAY.json
│   ├── RUNTIME-HOST-CHAT.json
│   └── ...
└── runtime-env/
    ├── RUNTIME-HOST-SYSTEM.json
    ├── RUNTIME-HOST-GATEWAY.json
    └── ...

Two files per runtime:

File	Purpose
`runtimes/<runtimeId>.json`	The runtime record (this page)
`runtime-env/<runtimeId>.json`	The per-runtime environment file consumed by the runner

`IHostRuntimeRecord` fields

Field	Type	Purpose
`runtimeId`	string	Stable runtime identity
`packageRef`	string?	The package + version this runtime serves (e.g. `@open-matrix/chat@0.2.9`)
`packageDir`	string?	Absolute path on disk to the package directory
`environment`	string?	The `--env <name>` value used at `up` time
`pid`	number?	OS pid of the runtime process (when running)
`status`	enum	`starting` \| `running` \| `stopping` \| `stopped` \| `failed`
`startup`	enum	`manual` \| `auto`
`restart`	enum	`never` \| `always` \| `on-failure`
`startedAt`	ISO date	When the runtime was last started
`stoppedAt`	ISO date	When the runtime was last stopped
`updatedAt`	ISO date	When the record was last written
`runtimeMount`	string?	The runtime's primary control mount
`controlMount`	string?	The runtime's control-actor mount
`runtimeWireRoot`	string?	The wire root for this runtime (e.g. `COM.NIMBLETEC.RICHARD-SANTOMAURO`)
`localMounts`	string[]	All actor mounts the runtime has registered
`metadata`	object	Free-form blob: source command, transport snapshot, webapp info, etc.

`IHostRuntimeStartSpec` — the input shape

When you run hivecast up, the CLI assembles an IHostRuntimeStartSpec (packages/host-service/src/types.ts:98-115) and hands it to runtime.start. The supervisor then writes the resulting IHostRuntimeRecord:

Field	From	Notes
`runtimeId`	`--id` or auto-allocated	Stable id
`packageDir`	resolved from positional or registry	Absolute path
`packageRef`	from `package.json:name@version`	When known
`environment`	`--env` value	Default `host`
`startup`	`--startup`	Default `manual`
`restart`	`--restart`	Default `never`
`runtimeWireRoot`	from Host status	The current wire root
`runtimeMount`, `controlMount`	derived from `runtimeId`
`command`, `args`	the command to spawn	Default is the bundled `matrix run`
`cwd`, `env`	optional overrides
`readyTimeoutMs`	`--timeout`	Default 30000
`localMounts`	declared mounts	Includes runtimeMount + controlMount + package mounts
`metadata`	source/target/transport/webapp blob	Used by `system.runtimes` and the gateway

A real example

<host-home>/runtimes/RUNTIME-HOST-CHAT.json:

json

{
  "runtimeId": "RUNTIME-HOST-CHAT",
  "packageRef": "@open-matrix/chat@0.2.9",
  "packageDir": "/tmp/matrix-home/packages/global/node_modules/@open-matrix/chat",
  "environment": "hivecast",
  "pid": 18432,
  "status": "running",
  "startup": "auto",
  "restart": "always",
  "startedAt": "2026-05-05T15:42:01.117Z",
  "updatedAt": "2026-05-05T15:42:11.348Z",
  "runtimeMount": "system.runtimes.chat-host",
  "controlMount": "system.runtimes.chat-host.control",
  "runtimeWireRoot": "COM.NIMBLETEC.RICHARD-SANTOMAURO",
  "localMounts": [
    "chat",
    "chat.conversation",
    "chat.security-realm",
    "chat.topic-claims",
    "system.runtimes.chat-host",
    "system.runtimes.chat-host.control"
  ],
  "metadata": {
    "source": "matrix-cli",
    "target": "@open-matrix/chat",
    "envFile": "/tmp/matrix-home/runtime-env/RUNTIME-HOST-CHAT.json",
    "transport": { "...": "..." },
    "controlReadyTimeoutMs": 30000,
    "autoStartPriority": 25,
    "serve": true,
    "webapp": {
      "appName": "chat",
      "displayName": "Chat",
      "navOrder": 30,
      "shells": ["platform", "edge"],
      "assetMount": "system.gateway.http.routes.chat-host",
      "origin": "http://127.0.0.1:5005",
      "port": 5005
    }
  }
}

Lifecycle of a record

mermaid

stateDiagram-v2
    [*] --> starting: hivecast up
    starting --> running: control.ready
    running --> stopping: hivecast down
    stopping --> stopped: clean exit
    stopping --> failed: timeout / kill
    running --> failed: process exit
    failed --> starting: restart policy fires
    stopped --> starting: hivecast up

The record persists across all transitions; updatedAt ticks whenever the status changes.

Runtime instances ​

On-disk layout ​

IHostRuntimeRecord fields ​

IHostRuntimeStartSpec — the input shape ​

A real example ​

Lifecycle of a record ​