Runtime hosts (operator workflow)

For the conceptual introduction, see Overview / Runtime hosts. This page is the operator-facing workflow: install, start, stop, declare runtimes, inspect health.

Install a Host

hivecast install --home /tmp/matrix-home
# or to skip auto-start:
hivecast install --home /tmp/matrix-home --no-start

This creates the <host-home>/ directory layout, drops the bundled NATS binary, generates host.json, seeds the system + global package store, registers the default runtime targets, and (unless --no-start) starts everything.

The wrapper at projects/matrix-3/packages/hivecast/bin/hivecast.mjs:1738-1769 dispatches to installHostProduct.

Start / stop

hivecast start --home /tmp/matrix-home
hivecast stop  --home /tmp/matrix-home

start brings up the supervisor + NATS. stop tears down both.

Inspect

hivecast status   --home /tmp/matrix-home
hivecast runtimes --home /tmp/matrix-home
matrix invoke host.control status '{}'   --home /tmp/matrix-home
matrix invoke system.runtimes runtimes.list '{}' --home /tmp/matrix-home

hivecast status prints overall health. hivecast runtimes lists the runtime records. host.control status returns the supervisor's view (PIDs, last starts, errors). system.runtimes runtimes.list returns the bus-registered runtimes.

A healthy Host shows the same runtime IDs in host.control and system.runtimes.

Declare a new runtime

matrix up @open-matrix/some-package --serve --port 5050 \
  --runtime-id MY-PKG --env hivecast --startup auto --restart always \
  --home /tmp/matrix-home

matrix up writes a runtime record under <host-home>/runtimes/<runtime-id>.json and (with --startup auto) starts it immediately.

Or via direct host.control invocation:

matrix invoke host.control runtimes.declare '{
  "runtimeId": "MY-PKG",
  "package": "@open-matrix/some-package",
  "mount": "my.pkg",
  "env": "hivecast",
  "serve": true,
  "port": 5050,
  "startup": "auto",
  "restart": "always"
}'

Lifecycle ops

# Direct lifecycle
matrix invoke system.runtimes runtimes.start   '{"mount":"chat"}'
matrix invoke system.runtimes runtimes.stop    '{"mount":"chat"}'
matrix invoke system.runtimes runtimes.reload  '{"mount":"chat"}'
matrix invoke system.runtimes runtimes.restart '{"mount":"chat"}'

# Via host.control
matrix invoke host.control runtimes.start  '{"runtimeId":"CHAT"}'
matrix invoke host.control runtimes.stop   '{"runtimeId":"CHAT"}'

The host.control ops operate on runtimeId; system.runtimes ops operate on mount. Both should converge to the same outcome on a healthy Host.

Reseed after corruption

If <host-home>/runtimes/<runtime-id>.json got truncated to zero bytes (a historical bug), hivecast seed self-heals:

hivecast seed --home /tmp/matrix-home

The output reports runtimeRecords.healthy and runtimeRecords.corrupt[]. Subsequent hivecast start reseeds empty records from desired state.

Per-Device differences

A user's local Device runs the same Host Service supervisor. The differences are configuration:

• auth.providers.google.clientId/clientSecret is set on the platform Host, unset on a local Device.
• externalUrl is https://hivecast.ai on the platform, the local hostname on a Device.
• The platform Host typically pins HTTP port; a Device often uses auto-allocation.

The wrapper assumes the platform role only when explicitly configured for it (Google OIDC credentials present, public TLS termination upstream). Otherwise it runs as a local Host.

Common health problems

Symptom	Likely cause	Fix
hivecast start exits "NATS already running on port"	A previous NATS sibling did not stop cleanly.	hivecast stop then hivecast start; or kill the stale nats-server PID.
host.control status shows running, but system.runtimes runtimes.list is empty	Register-with-system propagation hasn't finished.	Wait 5-10 seconds; check matrix-host.log.
/api/apps returns empty after install	The default runtime records didn't seed.	hivecast seed then hivecast start.
Pinned port collision	Another process holds the port.	Switch to --port 0 or kill the holder.

See Reference: Operational runbooks for full repair procedures.

Multi-Host on one Device (target)

The runtime-environment-multi-instance workstream tracks running multiple Host supervisors on one Device — e.g., a personal Host plus a per-Space sub-Host. Today the model is one Host per Device. Target state.

See also

• Overview / Runtime hosts — concept.
• Deployment profiles — target declarative model.
• Package versions — version semantics on records.
• Reference: Operational runbooks — repair procedures.

Source: projects/matrix-3/packages/hivecast/bin/hivecast.mjs for the wrapper. projects/matrix-3/packages/host-control/src/index.ts and projects/matrix-3/packages/host-service/src/host-state-store.ts for the supervisor.