Config

How a Device's local Host is configured — host.json, CLI flags, environment variables.

`host.json`

The per-Host config. Lives at <host-home>/host.json. Generated by hivecast install; operator-edited thereafter.

json

{
  "transport": {
    "root": "COM.GMAIL.RICHARD-SANTOMAURO"
  },
  "http": {
    "host": "127.0.0.1",
    "port": 3100
  },
  "auth": {
    "sessionSecret": "<32-byte-hex>",
    "providers": {
      "google": {
        "clientId": "...",
        "clientSecret": "..."
      }
    },
    "mode": "public-session"
  },
  "externalUrl": "https://hivecast.ai"
}

Field reference

Path	Meaning
`transport.root`	Authority root for this Host's bus traffic. Read by `system-auth` as `MATRIX_AUTHORITY_ROOT` fallback.
`http.host`	Bind address. `127.0.0.1` for local-only, `0.0.0.0` for platform Host (behind Caddy).
`http.port`	Gateway HTTP port. `0` for OS-allocated.
`auth.sessionSecret`	HMAC secret for session JWTs. Min 32 chars.
`auth.providers.google.clientId/clientSecret`	Google OIDC creds. Only set on the platform Host.
`auth.mode`	`public-session` (default) or other modes.
`externalUrl`	Public URL. On platform Host: `https://hivecast.ai`. On user Device: typically unset.

Editing rules

Stop the Host before editing: hivecast stop.
Edit JSON directly. Validate with jq . <host-home>/host.json (catches syntax errors).
Restart: hivecast start.
Some fields require restart even if changed at runtime; safe to always restart after editing host.json.

CLI flags

hivecast install and hivecast start accept overrides:

Flag	Effect
`--home <path>`	Use this Host home.
`--root <root>`	Override `transport.root`.
`--http-port <port	0
`--no-start` (`install` only)	Don't auto-start runtimes.
`--no-default-runtimes` (`start` only)	Skip default runtime startup.

hivecast login --device accepts:

Flag	Effect
`--cloud <url>`	Platform URL to pair to. Default `https://hivecast.ai`.
`--route-key <key>`	Space path.
`--device-name <name>`	Sets `hostName`.

Environment variables

system-auth reads (per index.ts:1250-1272):

Env	Effect
`MATRIX_HOST_HOME`	Override `host.home`.
`MATRIX_AUTH_SESSION_SECRET`	Override `auth.sessionSecret`.
`MATRIX_AUTHORITY_ROOT`	Override `transport.root`.
`EXTERNAL_URL`	Override `externalUrl`.
`GOOGLE_CLIENT_ID` / `GOOGLE_CLIENT_SECRET`	Override `auth.providers.google.*`.

Per CLAUDE.md Rule 6 (no hardcoded config values), config is layered: env → host.json → defaults. Env wins.

Per-Device defaults

A typical user Device install:

transport.root: derived from email domain at first OIDC sign-in (target — currently the platform pre-allocates).
http.host: 127.0.0.1.
http.port: auto-allocated (or 3100 if pinned).
auth.sessionSecret: generated by hivecast install.
auth.providers.google.*: unset (no local OAuth).
externalUrl: unset (local-only) or https://hivecast.ai after pairing (some flows set this).

Per-platform-Host defaults

The HiveCast cloud Host:

transport.root: AI.HIVECAST.HOST or the platform's authority root.
http.host: 0.0.0.0 (behind Caddy).
http.port: typically 3100.
auth.sessionSecret: deployed via env or secret store.
auth.providers.google.clientId/clientSecret: required for Google OIDC.
externalUrl: https://hivecast.ai.

Sensitive content

Per HiveCast Platform / Security / Secrets:

auth.sessionSecret — HMAC secret. Sensitive; rotate periodically.
auth.providers.google.clientSecret — Google OAuth secret. Rotate when Google requests.

Backups of host.json must be encrypted at rest.

Other config

<host-home>/runtimes/*.json — per-runtime records. See Installed packages and HiveCast Platform / Deployments / Runtime hosts.
<host-home>/credentials/ — Device identity files. See Pair.

Config ​

host.json ​

Field reference ​

Editing rules ​

CLI flags ​

Environment variables ​

Per-Device defaults ​

Per-platform-Host defaults ​

Sensitive content ​

Other config ​

See also ​