Config

A Host's deployment config is built from three layers. None of them contains credentials directly (those live behind Factotum, per CLAUDE.md Rule 4); each layer answers a different question.

Layer 1 — `host.json`

<host-home>/host.json is the Host process's config. Generated by hivecast install (see writeHostProductConfig in packages/hivecast/bin/hivecast.mjs:281-346). Shape: IMatrixHostConfig in packages/host-service/src/types.ts:50-60.

json

{
  "kind": "MatrixHostConfig",
  "version": 1,
  "home": "/tmp/matrix-home",
  "http": { "host": "127.0.0.1", "port": 3100 },
  "transport": {
    "root": "COM.NIMBLETEC.RICHARD-SANTOMAURO",
    "authorityRoot": "COM.NIMBLETEC.RICHARD-SANTOMAURO",
    "addressRoot": "COM.NIMBLETEC.RICHARD-SANTOMAURO",
    "nats": {
      "mode": "external",
      "url": "nats://127.0.0.1:4222",
      "wsUrl": "ws://127.0.0.1:4223",
      "port": 4222, "wsPort": 4223,
      "dataDir": "nats/host-default",
      "pidFile": "nats/host-default/nats-server.pid",
      "binaryPath": "bin/nats-server"
    }
  },
  "auth": { "mode": "local-client" },
  "runtimeStorage": { "recordsDir": "runtimes", "logsDir": "logs/runtimes" },
  "packageStorage": { "globalDir": "packages/global", "systemDir": "packages/system" }
}

This is read once on hivecast start. Edits require a Host restart. Do not hand-edit during normal operations; use hivecast install/hivecast operator paths.

Layer 2 — `runtime-env/<runtimeId>.json`

<host-home>/runtime-env/<runtimeId>.json is the per-runtime environment file the runner reads on startup. Written at hivecast up time by writeHostRuntimeEnvironment (packages/host-service/src/cli.ts:179-188). Shape matches IMatrixPackageEnvironment from packages/mx-cli/src/utils/package-environment.ts:6-35 — the same shape mx run --env <name> uses for .matrix/<env>.environment.json.

json

{
  "name": "host",
  "nats": {
    "mode": "external",
    "url": "nats://127.0.0.1:4222",
    "wsUrl": "ws://127.0.0.1:4223"
  },
  "runtime": {
    "root": "COM.NIMBLETEC.RICHARD-SANTOMAURO",
    "runtimeId": "RUNTIME-HOST-CHAT",
    "runtimeMount": "system.runtimes.chat-host",
    "controlMount": "system.runtimes.chat-host.control"
  },
  "http": { "enabled": true, "port": 5005 },
  "host": { "matrixDir": "/tmp/matrix-home" }
}

Each runtime gets its own file because runtimeId/runtimeMount/ ports vary per runtime even when the wire root and NATS endpoint do not.

Layer 3 — package config

The package's matrix.json:config block declares the package-level config schema, defaults, and providers. See Authoring → Config contract. The runtime resolves package config at startup using the providers in the order declared, with runtime-env and host.json available through the env provider.

Composition order

host.json
   │
   ▼
runtime-env/<runtimeId>.json
   │
   ▼
matrix.json:config.providers[]
   │
   ▼
what the actor sees

Each layer can override the previous one for fields it understands. For example, the wire root in host.json:transport.root flows down into runtime-env/<id>.json:runtime.root (they typically agree), and the package factory can override the runtime mount only at the deepest layer.

Where credentials go

CLAUDE.md Rule 4: through Factotum only. Concretely:

Credential	Lives at	Read by
HiveCast install id	`<host-home>/credentials/hivecast-install.json`	`mx-cli` link store
HiveCast device link	`<host-home>/credentials/hivecast-link.json`	`mx-cli` link store
NATS user JWT/seed	`<host-home>/credentials/nats/...`	NATS connection setup
Inference API tokens	`<MATRIX_HOME>/credentials/factotum/...`	`system.factotum` only
Registry tokens	`<MATRIX_HOME>/credentials/registry.json`	`mx publish`/`mx install`

None of these belong in host.json or runtime-env/<id>.json. Reference them indirectly (e.g. via secretRefs in matrix.service.json).

What if you need to change a runtime's config?

Today: stop the runtime, edit its runtime-env/<id>.json (or re-issue hivecast up with different flags so the file is regenerated), then start the runtime. The up/down cycle is the canonical mutation surface.

Target state — a mx config set --runtime <id> <key> <value> that edits the runtime env and signals the runtime to reload — is filed in WORKSTREAMS/runtime-environment-multi-instance/.

Config ​

Layer 1 — host.json ​

Layer 2 — runtime-env/<runtimeId>.json ​

Layer 3 — package config ​

Composition order ​

Where credentials go ​

What if you need to change a runtime's config? ​

See also ​