Config files

Every file that carries Host state. Read alongside Filesystem layout.

<host-home>/host.json — Host config

The authoritative configuration for one Host. Written by hivecast install (only if absent) and hivecast seed. Schema in projects/matrix-3/packages/host-service/src/types.ts:51-61.

{
  "kind": "MatrixHostConfig",
  "version": 1,
  "home": "/var/lib/hivecast",
  "externalUrl": "https://hivecast.ai",
  "http": {
    "host": "127.0.0.1",
    "port": 3100
  },
  "transport": {
    "root": "COM.OPEN-MATRIX.LOCAL.AUTHORITY",
    "authorityRoot": "COM.OPEN-MATRIX.LOCAL.AUTHORITY",
    "addressRoot": "COM.OPEN-MATRIX.LOCAL.AUTHORITY",
    "spaceId": "spc_7f3a9b2c",
    "routeKey": "alt.stories.ghost-stories.funny",
    "publicNamespace": "space.alt.stories.ghost-stories.funny",
    "nats": {
      "mode": "external",
      "url": "nats://127.0.0.1:4222",
      "wsUrl": "ws://127.0.0.1:4223",
      "credentialsRef": "file:credentials/factotum/hivecast-device-creds.creds",
      "port": 4222,
      "wsPort": 4223,
      "dataDir": "nats/host-default",
      "pidFile": "nats/host-default/nats-server.pid",
      "binaryPath": "bin/nats-server"
    }
  },
  "auth": {
    "mode": "local-client",
    "sessionSecret": "<32+ random bytes hex>",
    "actorTimeoutMs": 30000,
    "providers": {
      "google": {
        "clientId": "...",
        "clientSecret": "..."
      }
    }
  },
  "runtimeStorage": {
    "recordsDir": "runtimes",
    "logsDir": "logs/runtimes"
  },
  "packageStorage": {
    "globalDir": "packages/global",
    "systemDir": "packages/system"
  }
}

Field reference (selected)

Field	Type	Default	Notes
kind	string	MatrixHostConfig	Required exact value
version	number	1	Required exact value
home	string	absolute path of <host-home>	Self-referential
externalUrl	string | undefined	unset	Public URL the Host advertises (cloud-platform Hosts only)
http.host	string	127.0.0.1 (loopback) or 0.0.0.0 (container)	Bind host
http.port	number | null	3100	null = OS-allocate
transport.root	string	COM.OPEN-MATRIX.LOCAL.AUTHORITY	Wire root for the Host's local bus traffic. Deprecated alias for authorityRoot but still primary in current code
transport.authorityRoot	string	same as root	Account/Space authority root that owns the current Host link
transport.addressRoot	string	same as root	Public actor address root advertised to bootstrap
transport.nats.mode	enum	external	external = host-service connects to a separate broker; embedded = host-service starts its own (legacy)
transport.nats.url	string	nats://127.0.0.1:4222	Broker URL
transport.nats.wsUrl	string	ws://127.0.0.1:4223	WebSocket URL
transport.nats.credentialsRef	string	absent	URI / file: path to JWT credentials
auth.mode	enum	local-client	local-client (loopback-trust) or public-session (OAuth + session cookie)
auth.sessionSecret	string	unset	HMAC secret for session cookies (required for public-session)
auth.actorTimeoutMs	number	30000	Session timeout
runtimeStorage.recordsDir	string	runtimes	Relative to home
runtimeStorage.logsDir	string	logs/runtimes	Relative to home
packageStorage.globalDir	string	packages/global	User-facing package store
packageStorage.systemDir	string	packages/system	System-internal package store

writeHostProductConfig in hivecast.mjs:281-346 writes the wrapper-default shape; defaultHostConfig in host-paths.ts:16-48 is the host-service equivalent.

<host-home>/host.status.json — live status

Written by host-service while running. Cleared on clean stop. Schema in types.ts:121-156.

{
  "kind": "MatrixHostStatus",
  "version": 1,
  "status": "running",
  "pid": 12345,
  "home": "/var/lib/hivecast",
  "root": "COM.OPEN-MATRIX.LOCAL.AUTHORITY",
  "authorityRoot": "COM.OPEN-MATRIX.LOCAL.AUTHORITY",
  "addressRoot": "COM.OPEN-MATRIX.LOCAL.AUTHORITY",
  "supervisorMount": "system.runtimes.RUNTIME-HOST-LOCAL-XXXX-SUPERVISOR",
  "startedAt": "2026-05-04T16:31:00Z",
  "updatedAt": "2026-05-04T16:32:11Z",
  "http": {
    "host": "127.0.0.1",
    "port": 3100,
    "origin": "http://127.0.0.1:3100"
  },
  "transport": {
    "root": "COM.OPEN-MATRIX.LOCAL.AUTHORITY",
    "authorityRoot": "COM.OPEN-MATRIX.LOCAL.AUTHORITY",
    "addressRoot": "COM.OPEN-MATRIX.LOCAL.AUTHORITY",
    "nats": {
      "mode": "external",
      "url": "nats://127.0.0.1:4222",
      "wsUrl": "ws://127.0.0.1:4223"
    }
  }
}

status is one of starting, running, stopping, stopped. The running state also has a live pid whose aliveness is the actual signal — a stale host.status.json with a dead pid is detected and overwritten by the next start.

<host-home>/runtimes/<id>/runtime.json — per-runtime record

See Local Device → Runtime records for the full reference. Schema in types.ts:79-96.

<host-home>/nats/host-default/nats-server.conf — NATS config

Generated by ensureNatsConfigFile (hivecast.mjs:606-624). Regenerated on every hivecast start to stay consistent with host.json.

host: "127.0.0.1"
port: 4222
jetstream {
  store_dir: "<MATRIX_HOME>/nats/host-default"
}
websocket {
  host: "127.0.0.1"
  port: 4223
  no_tls: true
}

The .deb install writes a similar file to /var/lib/hivecast/nats/service/nats-server.conf from postinst (scripts/build-deb-installer.js:334-345):

host: "${HIVECAST_BIND_HOST}"
port: 4222
jetstream {
  store_dir: "/var/lib/hivecast/nats/service/jetstream"
}
websocket {
  host: "${HIVECAST_BIND_HOST}"
  port: 4223
  no_tls: true
}

HIVECAST_BIND_HOST is 127.0.0.1 for normal installs, 0.0.0.0 for containers (auto-detected via /.dockerenv or /proc/1/cgroup).

<host-home>/credentials/hivecast-install.json — install identity

Created by ensureHiveCastInstallIdentity (projects/matrix-3/packages/mx-cli/src/utils/hivecast-link-store.ts). Idempotent — re-running install reuses the existing installId.

{
  "kind": "HivecastInstallIdentity",
  "version": 1,
  "installId": "<random>",
  "createdAt": "2026-04-01T00:00:00Z",
  "updatedAt": "2026-05-04T00:00:00Z"
}

<host-home>/credentials/hivecast-link.json — pairing link record

Created by hivecast login --device (only if pairing succeeds). Removed by hivecast logout. Schema is owned by mx-cli/src/utils/hivecast-link-store.ts.

{
  "kind": "HivecastLink",
  "version": 1,
  "hostId": "...",
  "installId": "...",
  "hostName": "richard-laptop",
  "deviceSlug": "richard-laptop",
  "authorityRoot": "COM.NIMBLETEC.RICHARD-SANTOMAURO",
  "addressRoot": "COM.NIMBLETEC.RICHARD-SANTOMAURO",
  "spaceId": "spc_7f3a9b2c",
  "spacePath": "alt.stories.ghost-stories.funny",
  "routeKey": "alt.stories.ghost-stories.funny",
  "publicNamespace": "space.alt.stories.ghost-stories.funny",
  "principal": {
    "principalId": "...",
    "displayName": "Richard Santomauro",
    "email": "..."
  },
  "cloud": {
    "url": "https://hivecast.ai"
  },
  "credentialsRef": "file:credentials/factotum/hivecast-device-creds.creds",
  "linkedAt": "2026-05-04T16:32:11Z"
}

<host-home>/credentials/factotum/<provider>/... — per-provider credentials

Owned by Factotum. Inference provider tokens (Anthropic OAuth, Codex OAuth, OpenAI API key, etc) and the per-Device NATS JWT credential. Per CLAUDE.md Rule 4: only system.factotum reads/writes these. Never bundle them in diagnostic captures.

See also

• Filesystem layout
• Environment variables
• Local Device → Runtime records
• Cloud Account → Device pairing

Source: projects/matrix-3/packages/host-service/src/types.ts (full schema); projects/matrix-3/packages/host-service/src/host-paths.ts (default config); projects/matrix-3/packages/hivecast/bin/hivecast.mjs lines 281-346 (writeHostProductConfig) and 606-624 (ensureNatsConfigFile); projects/matrix-3/packages/hivecast/scripts/build-deb-installer.js lines 303-345 (.deb postinst config).