Runtime Host

A Runtime Host is the substrate's docker-engine: one process per machine that supervises runtimes, the substrate's containers. A runtime hosts one or more Matrix packages; the package's matrix.json declares the isolation level (shared / process / worker / vm); the Host honors the declaration. That is the model.

Motivation

The Runtime Host exists because actors need somewhere to run. Source code on disk and tarballs in a registry do not by themselves answer phone calls; something has to boot them, give them a bus to talk on, keep them alive across crashes, federate them with the rest of the world, and report what is actually running and how healthy it is. The Host is that something. It honors each package's declared isolation — co-tenanting compatible packages in one process, giving stricter ones their own — without forcing every author to think about supervision. Read these docs if you install or operate a Host on a workstation, container, or VPS, if you are writing a package whose isolation requirements matter, or if you are debugging why a runtime came up empty or refused to come up at all.

What this is, and why it exists

In the docker-for-actors framing (THESIS Part 1), the four substrate units are:

Substrate unit	Docker analogue	What this docs package covers
Package	Image	published artifacts (docs-registry, docs-package-lifecycle)
Runtime	Container	supervised processes that host Matrix actors — this docs package
Host	Docker engine + machine	the supervisor itself — this docs package
DeploymentInstance	Container instance	a running deployment of a package (P1.42 target state)

A Host owns one local NATS bus (or connects to an external one), spawns package runners as child processes, persists their lifecycle records to disk, recovers them after a crash, and exposes a control interface over NATS (host.control) and a CLI (hivecast, matrix). It does not instantiate actors itself. It does not implement HTTP, OAuth, sessions, inference, or UI. Those are package concerns.

The implementation lives in @open-matrix/host-service (projects/matrix-3/packages/host-service/src/). The wrapper that ships it to operators is hivecast (projects/matrix-3/packages/hivecast/).

Where this fits in the whole

This is substrate plumbing, not a vertical. The Host is what every vertical (Personal AI runtime, Inference market, Compositional UIs) ultimately runs on. Tier 1 (a user's local Host) and Tier 2 (a hosted/VPS Host) use the same code; only the operator changes.

For end-user product language ("Device", "Edge"), see docs-devices and docs-edge. A Device is a paired local install. A Host is the supervisor inside it. "Host" is internal vocabulary; "Device" is the user-facing term.

Multi-package runtimes (target shape)

Status: target state — multi-package runtimes ship with P1.40-a. Today's codebase implements a simpler one-package-per-runtime shape: each runtime hosts one package and the runtime ID encodes the package name (RUNTIME-HOST-...-CHAT). The substrate target is multi-package runtimes with declared per-package isolation; pages that describe "one package per runtime" are marking that as the present implementation while the target shape lands. Tracker: P1.40.

In the target shape:

• A package's matrix.json declares runtime.isolation: shared (co-tenanted with other shared packages in one Node process), process (its own Node process), worker (Node worker thread), or vm (sandboxed vm.Context).
• Default-runtime grouping co-tenants shared packages by substrate role: RUNTIME-HOST-...-CONTROL-PLANE (system aggregate, gateway, agents, inference-catalog), RUNTIME-HOST-...-USER-APPS (chat, director, flowpad, smithers, inference-settings).
• process-declared packages remain in their own runtimes.
• A fresh hivecast install produces ~4 runtimes per Host instead of 12.

The runtime is a substrate for actors, not "the runtime for one specific package." Read every "runtime hosts <package>" claim with that correction in mind.

Five-minute quickstart

Install a Host into a fresh home, start it, watch the supervised runtimes come up, hit a webapp.

# 1. Install + start a Host. No environment variables required.
node projects/matrix-3/packages/hivecast/bin/hivecast.mjs install \
  --home /tmp/matrix-home
node projects/matrix-3/packages/hivecast/bin/hivecast.mjs start \
  --home /tmp/matrix-home

# 2. Confirm liveness on the boundary endpoint.
curl -fsS http://127.0.0.1:3100/healthz | jq .

# 3. Inspect what's running. The bus is the authority.
matrix invoke system.runtimes runtimes.list '{}'
matrix invoke system.devices devices.list '{"includeOffline":true}'

# 4. Hit a supervised webapp.
#    http://127.0.0.1:3100/apps/edge/  ← local Device shell
#    http://127.0.0.1:3100/apps/web/   ← matrix-web (account/platform shell)

# 5. Stop cleanly.
node projects/matrix-3/packages/hivecast/bin/hivecast.mjs stop \
  --home /tmp/matrix-home

If port 3100 is in use, pass --http-port <N> to both install and start. The CLAUDE.md "First 10 Minutes" section is the canonical fresh-clone bootstrap.

Conceptual map

Question you have	Read
What is a Runtime Host? How does it differ from a runtime, a Device, or HiveCast cloud?	Overview
How do I install one — locally, as a Linux service, in a container?	Installation
How do I configure ports, NATS, storage, log policy?	Configuration
How does the Host start, stop, restart, recover runtimes?	Runtime Supervision
What is host.control, and how do other actors steer the Host?	Host Control Plane
Backup, restore, upgrade, rollback, diagnostics, uninstall	Operations
Filesystem layout, ports, JSON schemas, error codes	Reference

Audience

Operators running a local Host on a workstation, platform maintainers running Hosts in containers or on cloud workers, and package authors who need to know what the supervisor does and does not provide.

Sister docs

• docs-gateway — the HTTP front door served by one of the Host's supervised runtimes (@open-matrix/system-gateway-http).
• docs-package-lifecycle — how a package gets installed and brought up under a Host.
• docs-registry — where Host runtime/instance inventory ultimately lands as bus-actor projections.
• docs-devices — Device (the user-facing term for a paired local install) pairing and management.
• docs-edge — the local Device shell that talks to this Host's system.devices / system.runtimes.

Authoritative source

When this documentation and the code disagree, the code is correct. Pages list their sourceCode paths in frontmatter; cite them when reporting drift. Aspirational claims that are not in code today carry an explicit > **Status: target state — ships in v0.5/v1/etc.** callout.