Host install

hivecast install is the entry point that creates a Host home, drops the bundled NATS binary, mirrors the bundled package set, and (unless --no-start) brings up the Host plus default runtimes. This page walks through what each step does.

Synopsis

hivecast install [--no-start] [--root <root>] [--http-port <port|0|auto>] [--home <path>]

What runs, in order

From installHostProduct in hivecast.mjs:1511-1539:

1. seedHostProductHome() — lay out <MATRIX_HOME>.
2. assertHostProductInstallable() — sanity-check that the bundle has what's needed.
3. (unless --no-start) startHostProduct({ writeOutput: false }) — start NATS sibling + host-service supervisor + bootstrap default runtimes.
4. Print a single JSON object summarizing the result.

Step-by-step on disk

seedHostProductHome at hivecast.mjs:348-394 is the part that creates files. It:

1. Resolves <MATRIX_HOME>

In order of precedence:

1. --home <path> flag
2. MATRIX_HOME environment variable
3. ~/.matrix (or /var/lib/hivecast on .deb-managed installs)

The path is resolved to an absolute path before any file is written.

2. Ensures the directory layout

<MATRIX_HOME>/
├── packages/global/node_modules/   ← user-facing package store
├── packages/system/node_modules/   ← internal package store
├── runtimes/                       ← per-runtime records
├── runtime-env/                    ← per-runtime environment files
├── logs/runtimes/                  ← per-runtime stdout/stderr
└── bin/                            ← bundled NATS binary

mkdirSync(..., { recursive: true }) is idempotent — re-running install on an existing home is safe.

3. Writes host.json (only if absent)

writeHostProductConfig (hivecast.mjs:281-346) writes a fresh host.json only if one doesn't already exist. If it does exist, the existing config is preserved. The default shape:

{
  "kind": "MatrixHostConfig",
  "version": 1,
  "home": "<MATRIX_HOME>",
  "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",
    "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"
  }
}

Override the root with --root, the HTTP port with --http-port <n|0|auto>, the NATS port with -p / --port, the auth mode with --auth-mode or --public-session.

4. Mirrors the bundled package set

seedBundledHostPackages (hivecast.mjs:205-216) walks every package in the wrapper's dist/node_modules/ and copies each into both <MATRIX_HOME>/packages/global/node_modules/ and <MATRIX_HOME>/packages/system/node_modules/. The list is computed dynamically by listBundledPackageNames() so a fresh build picks up newly bundled packages without changing the wrapper.

5. Drops the NATS binary

copyFileIfPresent(<dist>/bin/nats-server[.exe], <MATRIX_HOME>/bin/nats-server[.exe], 0o755) copies the bundled NATS binary into the home. Skipped if the source-side binary doesn't exist (for builds without bundled NATS) — but assertHostProductInstallable will then throw before start.

6. Copies static assets

copyDirIfPresent(<dist>/webapps, <MATRIX_HOME>/webapps) and similarly for branding/. These are bundled-static assets used by the gateway.

What assertHostProductInstallable checks

hivecast.mjs:749-761:

Check	Failure mode
dist/host-service/cli.js exists	"Host Service CLI not found in HiveCast package" — the bundle is broken
<MATRIX_HOME>/bin/nats-server[.exe] exists	"Packaged nats-server binary was not installed into the Host home"
<MATRIX_HOME>/packages/global/node_modules/@open-matrix/matrix-edge exists	"Matrix Edge package was not installed into the Host package store"

If any check fails, install errors out with the message above and exits 1. The home is left in whatever state the failed step achieved (idempotent re-run will continue from there).

What happens if --no-start

The Host home is laid out and host.json is written, but no process is spawned. Use this for:

• staged container builds where the install layer is separate from the runtime layer
• preparing a home that you'll start later under a service manager
• diagnostic / setup scenarios where you want to inspect or modify config before start

After --no-start, run hivecast start to bring the Host up.

What happens with --start (default)

startHostProduct runs:

1. startNatsSibling(matrixHome) — spawns the bundled NATS as a detached sibling, writes its pidfile, waits up to 10s for the configured port to accept connections.
2. Spawns the host-service supervisor (node dist/host-service/cli.js start --home <MATRIX_HOME>) detached, with stdout/stderr to <MATRIX_HOME>/logs/host.{stdout,stderr}.log.
3. Waits for <MATRIX_HOME>/host.status.json to land with status: "running".
4. Waits for the host-service CLI to be ready (probes host-service status until it succeeds).
5. Calls bootstrapDefaultHostRuntimes to register the default runtime targets.

Each default runtime is brought up with policy --startup auto --restart always --auto-start-priority <0..40> --control supervisor. Priority comes from hostDefaultRuntimeTargets (hivecast.mjs:28-39) — system first, gateway/web/edge before user-visible apps.

Idempotence

Re-running hivecast install against an existing home:

• host.json is preserved if present
• <MATRIX_HOME>/credentials/hivecast-install.json is preserved (the installId is durable)
• bundled packages are re-mirrored — any local edits you made there will be clobbered
• the NATS binary is overwritten with the bundle's copy
• if a Host is already running, startHostProduct returns the existing status without restarting

Treat the package stores under <MATRIX_HOME>/packages/{global,system}/node_modules/ as derived data. Do not edit them in place.

See also

• Service install — what dpkg -i adds on top of a hivecast install.
• Start / stop / restart — lifecycle.
• Reference → Filesystem layout — the full set of files.
• CLI → hivecast host — wrapper-side reference.

Source: projects/matrix-3/packages/hivecast/bin/hivecast.mjs lines 281-394 (seedHostProductHome, writeHostProductConfig) and 1511-1539 (installHostProduct); projects/matrix-3/packages/host-service/src/host-paths.ts lines 7-48 (defaults).