Runtime hosts

A Runtime Host is a process that supervises one or more package runtimes on a Device. The platform's RuntimeHostView distinguishes "the supervisor process" from "the runtimes it supervises." This page explains why that distinction matters and how the dashboard renders it.

The four-noun stack

Per P1.22a (Device / Runtime Host reachability topology), the platform navigation model is:

HiveCast account / authority namespace
  -> Device
    -> Runtime Host
      -> Runtime / Package
        -> App Route
          -> Actor

These are five distinct nouns. The dashboard must not collapse them. Earlier dashboard iterations called every runtime a "host" — that was wrong. A Device can run more than one Runtime Host (a Host Service supervisor is one; a per-Space sub-Host might be another), and one Runtime Host can supervise many runtimes.

Source of truth: system.runtimes

system.runtimes is the platform actor that owns runtime inventory. Its public ops (per RuntimeManagerActor.accepts):

Op	Description
runtimes.ps	List runtime inventory and deployment slice status. Alias of runtimes.list.
runtimes.list	List runtime inventory and deployment slice status.
runtimes.status	Get runtime status and deployment slice status.
runtimes.instances	List declared and observed deployment instances.
runtimes.reconcile	Reload installed and folder-backed package state.
runtimes.start / stop / reload / remove / restart	Direct lifecycle control on a mount.
runtimes.register	Register a runtime within this namespace.
runtimes.deregister	Remove a runtime from the registry.
runtimes.heartbeat	Refresh runtime registration.
runtimes.registered	List all registered runtimes in this namespace.

Source: projects/matrix-3/packages/system-runtimes/src/RuntimeManagerActor.ts:156-171.

A runtime is a registered execution context. Its record (IRegisteredRuntime, lines 130-148) includes runtimeId, type, app, sessionMount, actorCount, claims, inventoryMode, an inventory array (mounts the runtime owns), catalogMount, runtimeMount, controlMount, and requiredPackages.

What a Runtime Host is

A Runtime Host is a supervisor process that owns multiple runtime registrations. On a typical user Device:

• The local Host Service supervisor is one Runtime Host.
• Its host.control mount is the Runtime Host's control surface.
• Its runtimes.list enumerates the runtimes it supervises (system, host-control, system-gateway-http, matrix-web, matrix-edge, director, chat, inference-settings, etc.).

In multi-Host topologies (one Device running both a personal and a per-Space sub-Host), each supervisor is a distinct Runtime Host. The dashboard renders them as separate RuntimeHostView groups, each with its own runtime count and app-route attribution.

RuntimeHostView in the dashboard

Per P1.22 progress notes (commit 3f2c06ee):

An explicit derived RuntimeHostView model. Device cards now distinguish runtime host count from runtime row count instead of calling every runtime a host.

A live proof example: a Gmail Device shown as 1 runtime host · 8 runtimes · 4 web apps. The single RuntimeHostView is install_<installIdShort>:host.control with host control, authority root, wire root, and public route metadata.

The RuntimeHostView derivation (in matrix-web and the system.devices projection) is:

1. Read system.devices.devices.list for the principal — yields linked Devices and their runtime summaries.
2. For each Device, group runtimes by their supervisor. Today there is exactly one supervisor per Device (the Host Service install). Multi-Host grouping is target state per P1.22 closure prerequisites.
3. Each RuntimeHostView carries: id (e.g. install_xxx:host.control), hostControlMount, authorityRoot, wireRoot, routeKey, publicNamespace, the count of runtimes it supervises, and the count of declared webapps among those runtimes.

App-route attribution: the dashboard groups Chat, Director, Edge, etc., under the Runtime Host that registered them, not flat under the Device. This matters when a Device runs more than one Host (the future per-Space sub-Host case).

Why this matters

Three operational implications:

1. Restarting a Runtime Host restarts all its runtimes. host.control host.restart cycles every runtime under that Host. A user who restarts the Host Service supervisor takes Chat, Director, Edge, and inference offline simultaneously on that Device.
2. Per-runtime ops are scoped to the registering Host. runtimes.start, runtimes.stop operate within one Runtime Host. A platform-side action targeting a Device must specify the Runtime Host explicitly when more than one exists.
3. Federation goes Host-to-Host, not runtime-to-runtime. A Device's outbound NATS leaf is per-Host (per supervisor). Multi-Host Devices establish multiple leaves.

What you can verify today

# Count runtime hosts and runtimes on a Device
matrix invoke host.control status '{}' --home /tmp/matrix-home
# Returns the Host's supervisor metadata and the runtime records it owns.

matrix invoke system.runtimes runtimes.list '{}' --home /tmp/matrix-home
# Returns the registered runtimes — should match host.control's runtime count
# minus deployment slices that haven't yet registered with system.runtimes.

matrix invoke system.devices devices.list '{"includeOffline":true}'
# Platform-account-facing facade. Each Device row carries
# runtimeHostCount and runtimes (filtered to webapps).

A healthy Device shows the same runtime IDs in host.control and system.runtimes after register-with-system propagates. Discrepancies are debugging signal — see Reference: Operational runbooks.

Target state

• Multi-Runtime-Host fixture acceptance. P1.22 lists this as an open closure prerequisite: "one Device with two control mounts renders two RuntimeHostView groups with correct app-route/runtime-control attribution." Today the derivation produces one RuntimeHostView per Device.
• Per-Runtime-Host control-mount probes on the dashboard. Today the dashboard probes system.runtimes.<runtimeId>.control per runtime; a per-Host probe would call host.control on the supervisor.
• Per-Space sub-Hosts on a single Device. The runtime-environment-multi-instance workstream owns this case. Schema-ready, no scheduler integration yet.

See also

• Devices — the parent noun.
• Package deployments — what runs in a runtime.
• Deployments / Runtime hosts — operator workflow for managing Runtime Hosts.
• Reference: Actor surfaces — full op list for system.runtimes.

Source: projects/matrix-3/packages/system-runtimes/src/RuntimeManagerActor.ts for the actor implementation. WORKSTREAMS/loose-ends/items/P1.22-dashboard-device-navigation-edge-parity.md and P1.22a-device-runtime-host-reachability-topology.md for the dashboard topology contract and the closure prerequisites.