Environment variables

Every env var the wrapper, host-service, and the .deb install script read.

Wrapper (hivecast CLI)

MATRIX_HOME

Default Host home directory if --home <path> is not given. Read by resolveMatrixHome (hivecast.mjs:87-89):

function resolveMatrixHome() {
  return resolve(readOption('--home') || process.env.MATRIX_HOME || join(homedir(), '.matrix'));
}

Set in	Value
.deb install via the wrapper at /usr/bin/hivecast	/var/lib/hivecast (set by the bash wrapper)
.deb install via systemd unit	/var/lib/hivecast (set by Environment= in hivecast-host.service)
Source-checkout install (default)	~/.matrix
Source-checkout install (override)	whatever you set

MATRIX_HOST_HOME

Synonym/alias used by host-service. The wrapper sets MATRIX_HOST_HOME=<resolved> in the child env when spawning host-service. host-service reads it via host-paths.ts:6:

export const MATRIX_HOST_HOME_ENV = 'MATRIX_HOST_HOME';

In practice they're set together. The wrapper-side bash wrapper for .deb sets both:

export MATRIX_HOME="${MATRIX_HOME:-/var/lib/hivecast}"
export MATRIX_HOST_HOME="${MATRIX_HOST_HOME:-$MATRIX_HOME}"

(scripts/build-deb-installer.js:87-101.)

HIVECAST_SESSION_SECRET / SESSION_SECRET

HMAC secret for session cookies on public-session Hosts. Read by seedHostProductHome at hivecast.mjs:364:

const sessionSecret = readOption('--session-secret') 
  || process.env.HIVECAST_SESSION_SECRET 
  || process.env.SESSION_SECRET 
  || null;

Required when auth.mode: 'public-session'. Should be 32+ random bytes (hex or base64). For local-client Hosts (the default), it's optional/unused.

HIVECAST_SKIP_DEFAULT_RUNTIMES

If set to 1, bootstrapDefaultHostRuntimes returns immediately without registering any runtimes (hivecast.mjs:1415):

if (process.env.HIVECAST_SKIP_DEFAULT_RUNTIMES === '1' || hasFlag('--no-default-runtimes')) {
  return [];
}

Use for staged container images where the install layer should be empty and runtimes are brought up by a later hivecast up step.

HIVECAST_BIND_HOST

Read by the .deb postinst (scripts/build-deb-installer.js:291-296):

if [ -z "${HIVECAST_BIND_HOST:-}" ]; then
  HIVECAST_BIND_HOST="127.0.0.1"
  if [ -f /.dockerenv ] || grep -qaE "(docker|containerd|kubepods)" /proc/1/cgroup 2>/dev/null; then
    HIVECAST_BIND_HOST="0.0.0.0"
  fi
fi

Override the auto-detected bind host for the .deb install's first config write. Useful for staging containers that don't trip the auto-detection.

HIVECAST_RUN_USER / HIVECAST_RUN_GROUP

.deb postinst variables that drive workstation-user takeover. The postinst falls back to ${SUDO_USER} if available; export these to override.

HIVECAST_OPERATOR_COMMAND

Set by the wrapper when spawning an operator script (hivecast.mjs:1718-1721). The operator script reads it for self-identification. Never set this externally.

Host Service (host-service CLI)

MATRIX_HOST_HOME

Same as above — host-service's preferred env var name.

Standard Node env vars

NODE_ENV, DEBUG, etc. are passed through unchanged. Use sparingly; the wrapper doesn't filter them.

NATS sibling

The bundled NATS binary reads no HiveCast-specific env vars. Configuration is via the conf file at <host-home>/nats/host-default/nats-server.conf.

Per-runtime environment

Each runtime gets a process env composed of:

1. The wrapper's process env (cleared except PATH, MATRIX_HOST_HOME, etc).
2. Anything in <host-home>/runtime-env/<env>/<runtime-id>.env (sourced by the runtime spawn).
3. runtime.json metadata.env (if present).

The exact composition is owned by host-service; this list is illustrative. Per-runtime env is the right place for things like OPENAI_API_KEY for an inference runtime that needs it (though Factotum is the preferred path).

Bundled packages may read additional env vars

Each bundled package may read its own env vars at runtime:

Package	Env var	Effect
@open-matrix/system-gateway-http	MATRIX_GATEWAY_HTTP_HOST, MATRIX_GATEWAY_HTTP_PORT	Override gateway HTTP bind
@open-matrix/inference-settings	varies	Per-provider override
@open-matrix/system-auth	HIVECAST_GOOGLE_CLIENT_ID, HIVECAST_GOOGLE_CLIENT_SECRET, etc.	OAuth provider creds (when not in host.json)

Refer to each package's own documentation. The docs-package-lifecycle package (separate) covers the package-level env var contract.

Things that are NOT env vars

• The Host's authority root — set in host.json transport.root / authorityRoot, not via env. CLI flag --root overrides during install.
• The HTTP port — set in host.json http.port, CLI flag --http-port. No env var.
• The NATS port — set in host.json transport.nats.port, CLI flag --port / -p. No env var.

Per CLAUDE.md Rule 9 ("No hardcoded config values — use environment/Host config, package metadata, or actor state"), config sources have a defined precedence; env vars are one of several inputs, not the first.

See also

• Config files — what env vars influence in host.json.
• Filesystem layout — where the configs live.
• Local Device → Service install — how systemd Environment= lines feed in.

Source: projects/matrix-3/packages/hivecast/bin/hivecast.mjs lines 87-89 (MATRIX_HOME), 364 (session secret), 1415 (skip-default-runtimes); projects/matrix-3/packages/host-service/src/host-paths.ts lines 6-13 (MATRIX_HOST_HOME); projects/matrix-3/packages/hivecast/scripts/build-deb-installer.js lines 87-101 (bash wrapper exports), 291-296 (HIVECAST_BIND_HOST).