Local install

A local install is the simplest way to run a Runtime Host. It does not touch systemd, launchd, or the Service Control Manager. The Host runs as a normal user process. You start and stop it with the hivecast CLI.

This is the right install mode for:

• Per-user laptops.
• Developer workstations.
• macOS and Windows machines (the only supported install on those platforms today).
• Inside a container that already has its own init (the worker cell sets this up — see Docker / container mode).

It is not the right mode for:

• Multi-user shared machines.
• Servers where the Host must survive a logout.
• Production Linux deployments — use the .deb (see Linux systemd).

What hivecast install does

projects/matrix-3/packages/hivecast/bin/hivecast.mjs:1738-1789 dispatches install to the local installHostProduct handler. Concretely:

1. Picks <host-home> from --home, then MATRIX_HOME, then ~/.matrix.

2. Creates <host-home>/ if missing; lays out runtimes/, runtime-env/, logs/, logs/runtimes/, packages/system, packages/global.

3. Drops the bundled nats-server binary into <host-home>/bin/.

4. Generates host.json (defaults from projects/matrix-3/packages/host-service/src/host-paths.ts:16-48).

5. Generates credentials/hivecast-install.json if it does not already exist (idempotent).

6. Seeds <host-home>/packages/system/node_modules/ from the wrapper's bundled dist/node_modules/ snapshot.

7. Registers the default runtime targets defined in hivecast.mjs:28-39:

   Target	Runtime key	Auto-start priority	--serve
   system	SYSTEM	0	no
   @open-matrix/host-control	HOST-CONTROL	2	no
   @open-matrix/system-gateway-http	GATEWAY	5	no
   @open-matrix/matrix-web	WEB	10	yes
   @open-matrix/matrix-edge	EDGE	15	yes
   @open-matrix/director	DIRECTOR	20	yes
   @open-matrix/chat	CHAT	25	yes
   @open-matrix/inference-settings	INFERENCE-SETTINGS	30	yes
   @open-matrix/flowpad	FLOWPAD	35	yes
   @open-matrix/smithers	SMITHERS	40	yes

8. Unless --no-start is passed, runs hivecast start immediately after.

hivecast start brings up NATS as an independent sibling process (so a Host crash does not take NATS down — see hivecast.mjs:561-723 and the comment at hivecast.mjs:561-582), then spawns the host-service supervisor against <host-home>.

Recipe

# Install into a fresh home (port 0 = let the OS pick).
node projects/matrix-3/packages/hivecast/bin/hivecast.mjs install \
  --home /tmp/matrix-home \
  --http-port 0

# Verify
curl -fsS http://127.0.0.1:<allocated-port>/healthz | jq .
node projects/matrix-3/packages/hivecast/bin/hivecast.mjs status --home /tmp/matrix-home
node projects/matrix-3/packages/hivecast/bin/hivecast.mjs runtimes --home /tmp/matrix-home

# Browse
# http://127.0.0.1:<port>/apps/web/   ← matrix-web (account/platform shell)
# http://127.0.0.1:<port>/apps/edge/  ← matrix-edge (Device shell)

# Stop
node projects/matrix-3/packages/hivecast/bin/hivecast.mjs stop --home /tmp/matrix-home

To pin a known port, pass --http-port 3100.

What you do not get

• No restart on machine reboot.
• No log rotation beyond what runtimes write to their own log files.
• No system-wide hivecast binary on $PATH — invoke through the bundled bin/hivecast.mjs, or symlink it manually.

Underlying CLI

If you want to run host-service directly without the wrapper, the four verbs are init, start, status, runtimes, stop — projects/matrix-3/packages/host-service/src/cli.ts:45-265. The wrapper only adds NATS sibling supervision and default runtime registration.

See also

• Service install
• Host config
• Filesystem layout
• Host lifecycle