Gateway config

The gateway reads its configuration from three sources in order:

<host-home>/host.json (the canonical config file)
Environment variables (MATRIX_HOST_HOME, HIVECAST_RELEASE_*)
CLI flags passed to hivecast install / hivecast start

host.json

Per IMatrixHostConfig in projects/matrix-3/packages/system-gateway-http/src/host-config-types.ts:

typescript

interface IMatrixHostConfig {
  kind: 'MatrixHostConfig';
  version: 1;
  home: string;
  externalUrl?: string;
  http: { host: string; port: number | null };
  transport: {
    authorityRoot?: string;
    spaceId?: string;
    routeKey?: string;
    publicNamespace?: string;
    root: string;            // legacy, prefer authorityRoot
    nats: {
      mode: 'embedded' | 'external';
      url?: string;
      wsUrl?: string;
      credentialsRef?: string;
      port?: number;
      wsPort?: number;
      dataDir?: string;
      pidFile?: string;
      binaryPath?: string;
    };
  };
  auth: {
    mode: 'local-client' | 'public-session';
    sessionSecret?: string;
    issuer?: string;
    actorTimeoutMs?: number;
    providers?: { google?: { clientId?: string; clientSecret?: string } };
  };
  runtimeStorage: { recordsDir: string; logsDir: string };
  packageStorage: { globalDir: string; systemDir: string };
}

Fields the gateway directly reads

Field	Effect
`http.host`	Bind address (default `127.0.0.1`)
`http.port`	TCP port (default 3100). `null` means "OS-assigned."
`transport.authorityRoot` (or `transport.root`)	Bus prefix the gateway publishes/subscribes under
`transport.nats.url`	NATS URL the gateway client connects to
`transport.nats.wsUrl`	NATS WS URL the gateway proxies `/nats-ws` to (when not direct via Caddy)
`auth.mode`	`local-client` (no auth) or `public-session` (cookie/JWT auth)
`auth.sessionSecret`	Secret for signing session cookies in public-session mode
`runtimeStorage.recordsDir`	Where the gateway reads `runtime.json` files for `_loadHostRuntimeRecordRoutes`

Fields the gateway indirectly cares about

Field	Indirectly via
`packageStorage.systemDir` / `globalDir`	Asset endpoints' `distDir` resolves through these stores
`transport.routeKey` / `publicNamespace`	Bootstrap response, Space-route awareness

Environment variables

Variable	Effect
`MATRIX_HOST_HOME`	Override `<host-home>` path. Used by mx-cli, gateway, and the asset endpoint to resolve relative paths.
`HIVECAST_RELEASE_VERSION`	Override `releaseVersion` in `/healthz` response
`HIVECAST_RELEASE_COMMIT`	Override `releaseCommit` in `/healthz` response
`HIVECAST_RELEASE_PATH`	Override `releasePath` in `/healthz` response
`HIVECAST_SESSION_SECRET` / `SESSION_SECRET`	Fallbacks for `auth.sessionSecret` if not in `host.json`

Per release-metadata.ts and hivecast.mjs:281-346.

CLI flags

These flags affect what gets written to host.json at install time:

hivecast install [--no-start] [--root <root>] [--http-port <port|0|auto>]
                 [--nats-url <url>] [--nats-ws-url <url>]
                 [--credentials-ref <path>]
                 [-p|--port <natsport>] [--ws-port <wsport>]
                 [--auth-mode <mode>] [--public-session]
                 [--session-secret <secret>] [--hivecast]

Of these, the gateway-relevant ones:

Flag	Effect on `host.json`
`--root`	`transport.root` / `transport.authorityRoot`
`--http-port <n>`	`http.port = <n>`. `0` or `auto` → null (OS-assigned).
`--auth-mode <mode>`	`auth.mode`
`--public-session`	shorthand for `auth.mode = 'public-session'`
`--session-secret`	`auth.sessionSecret`

These are written once at install time. To change them after install, edit <host-home>/host.json and restart.

Defaults

Without flags, hivecast install writes:

json

{
  "kind": "MatrixHostConfig",
  "version": 1,
  "home": "<host-home>",
  "http": { "host": "127.0.0.1", "port": 3100 },
  "transport": {
    "root": "COM.OPEN-MATRIX.LOCAL.AUTHORITY",
    "authorityRoot": "COM.OPEN-MATRIX.LOCAL.AUTHORITY",
    "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" }
}

Note: NATS is mode: 'external' even for the local install — host-service treats the bundled NATS sibling process as an externally-managed collaborator, not a child it spawns.

Gateway config ​

host.json ​

Fields the gateway directly reads ​

Fields the gateway indirectly cares about ​

Environment variables ​

CLI flags ​

Defaults ​

See also ​