Runtime Host

Appearance

Environment variables ​

The Host reads a small set of environment variables and sets a small set on its spawned runtimes. There is no general-purpose env-var configuration system; everything else lives in host.json.

Variables the Host reads ​

MATRIX_HOST_HOME ​

MATRIX_HOST_HOME=/path/to/host-home

Selects the Host home directory. Resolution order (host-paths.ts:9-14):

  1. The CLI's --home <path> flag, if given.
  2. MATRIX_HOST_HOME env var.
  3. ~/.matrix.

Used by every Host-service CLI verb. Setting this before invoking hivecast/matrix lets you operate against a non-default home without remembering --home.

MATRIX_HOME ​

MATRIX_HOME=/path/to/host-home

The wrapper-level alias for MATRIX_HOST_HOME. The wrapper itself (hivecast.mjs:87-89) reads --home then MATRIX_HOME then ~/.matrix. Inside host-service the variable consulted is MATRIX_HOST_HOME. Setting both to the same value avoids surprises; the .deb postinst sets both (build-deb-installer.js:88-89).

MATRIX_NATS_SERVER_BINARY / NATS_SERVER_BINARY ​

MATRIX_NATS_SERVER_BINARY=/path/to/nats-server

Override the bundled NATS binary path (matrix-host-service.ts:1395-1399). Useful when:

  • Testing a NATS upgrade against an installed Host.
  • Running on an architecture where the bundled binary is wrong.
  • Building from source.

If unset, the Host uses host.json transport.nats.binaryPath, then falls back to a search-by-walk-up (see resolveNatsBinary, matrix-host-service.ts:1383-1426).

MATRIX_HOST_CURRENT_MX_CLI_PATH ​

MATRIX_HOST_CURRENT_MX_CLI_PATH=/path/to/mx-cli/dist/index.cjs

Used by the rolling-upgrade rewriter (resolveCurrentHiveCastMxCliPath, matrix-host-service.ts:1694-1703). When a runtime record persists the bundled mx-cli path (e.g. .../hivecast-0.1.24/.../mx-cli/...), auto-restart after an upgrade points at the new release path. Only relevant for installed wrapper releases, not for source dev loops.

MATRIX_DEVICE_HEARTBEAT_* (host-control runtime) ​

The host-control actor reads three env vars (HostControlActor.ts:76-84):

VariableDefaultEffect
MATRIX_DEVICE_HEARTBEAT_INTERVAL_MS15000how often device heartbeats fire
MATRIX_DEVICE_HEARTBEAT_TTL_MS45000TTL the cloud should treat the heartbeat as valid for
MATRIX_DEVICE_HEARTBEAT_TIMEOUT_MS5000per-call timeout for heartbeat RPCs

These are runtime-level env vars, not Host-process env vars. Set them on the host-control runtime via matrix up --env-file ... or via the runtime's environment file. Useful for tests; not recommended in production.

Standard Node env vars ​

The Host respects NODE_OPTIONS, NODE_PATH, TZ, etc. like any Node program. None are part of the Host contract.

Variables the Host sets on spawned runtimes ​

MatrixHostService.startRuntimeProcess (matrix-host-service.ts:382-388) injects three env vars into every spawned child:

ts
env: {
  ...process.env,
  ...(spec.env ?? {}),
  MATRIX_HOST_HOME: this._config.home,
  MATRIX_RUNTIME_ID: runtimeId,
  ...(spec.environment ? { MATRIX_ENV: spec.environment } : {}),
},
VariableValueUse
MATRIX_HOST_HOME<home>runtimes that need to read sibling state
MATRIX_RUNTIME_IDruntimeIdruntime self-identification in logs
MATRIX_ENV--env <name> (default host)runtimes that branch on env name

The runtime also receives whatever was in spec.env (the optional env block in the runtime record's metadata), inherited by the spawn. host.json is not projected into env vars; runtimes read their environment file via --env-file.

What the Host does NOT read ​

  • NODE_ENV. The Host does not check this; runtimes might.
  • HTTP_PROXY, HTTPS_PROXY. The Host's only outbound HTTP is the Device-Link heartbeat (HostControlActor.postCloudDeviceHeartbeat), which uses Node's built-in fetch. That respects the standard proxy env vars on Node 22+.
  • DEBUG. The Host does not have a debug-printf mode driven by env vars; observability is via actorLog() and the per-runtime stderr files.

Setting env vars in production ​

For systemd .deb installs, edit the unit drop-in:

sudo systemctl edit hivecast-host.service

Add:

ini
[Service]
Environment=MATRIX_NATS_SERVER_BINARY=/usr/local/bin/nats-server
Environment=MATRIX_DEVICE_HEARTBEAT_INTERVAL_MS=30000

Then sudo systemctl restart hivecast-host.service. The drop-in survives apt upgrade hivecast because it lives at /etc/systemd/system/hivecast-host.service.d/ not the package's own unit file at /lib/systemd/system/.

See also ​