HiveCast Product

Appearance

Install the CLI ​

You need the hivecast binary on your PATH before any other step works. There are two supported ways to get it: the .deb installer (Linux, what production uses) and a source-checkout build (any platform, for developers).

Status — present state: there is no npm install -g hivecast flow today. Issuing one will not work; the hivecast package is private to the workspace, and the binary is shipped through the .deb installer or built from source. Tracking the public-registry path as P1.16b in WORKSTREAMS/loose-ends/.

The .deb installer is the production path. It drops a hivecast binary at /usr/bin/hivecast, a matrix binary at /usr/bin/matrix, the bundled Node runtime at /opt/hivecast/node/bin/node, and registers the hivecast-nats.service and hivecast-host.service systemd units.

Build the .deb from this repo ​

bash
cd projects/matrix-3
pnpm --filter hivecast build
pnpm --filter hivecast build:deb
# Outputs: projects/matrix-3/packages/hivecast/native-dist/hivecast_<version>_<arch>.deb

<arch> is amd64 on x64 hosts and arm64 on arm64. The build script is projects/matrix-3/packages/hivecast/scripts/build-deb-installer.js.

Install on the target machine ​

bash
sudo dpkg -i hivecast_<version>_<arch>.deb
# or, if dependencies are missing:
sudo apt install ./hivecast_<version>_<arch>.deb

What the .deb does to your system ​

From scripts/build-deb-installer.js, the postinst script:

  • creates a hivecast system user/group (uses ${SUDO_USER} if available so the workstation user owns runtime files)
  • creates /var/lib/hivecast/ with 0750 permissions, owned by that user
  • writes /var/lib/hivecast/host.json with HTTP port 3100, NATS at nats://127.0.0.1:4222, ws at ws://127.0.0.1:4223, auth.mode: 'local-client'
  • writes /var/lib/hivecast/nats/service/nats-server.conf (port 4222, ws port 4223, JetStream store_dir)
  • runs hivecast seed to populate the bundled package store
  • caps journald at SystemMaxUse=2G via /etc/systemd/journald.conf.d/hivecast.conf
  • enables and restarts hivecast-nats.service then hivecast-host.service

After install:

bash
which hivecast        # /usr/bin/hivecast
which matrix          # /usr/bin/matrix
hivecast --help       # prints the command list
sudo systemctl status hivecast-host.service
sudo systemctl status hivecast-nats.service

The next quickstart page (Start a local host) covers verifying the Host is actually up.

Note (container/VM detection): the postinst script detects /.dockerenv or container cgroups and binds to 0.0.0.0 instead of 127.0.0.1 automatically. This means a container Host is reachable from the container's host network without extra config.

Option B — Source checkout (any platform, developers) ​

If you're working in this repo:

bash
git clone https://github.com/<your-fork>/matrix-work-harness.git
cd matrix-work-harness
pnpm install
pnpm --filter hivecast build
pnpm --filter @matrix/mx-cli build
pnpm --filter @open-matrix/host-control build
pnpm --filter @open-matrix/host-service build

This produces:

  • projects/matrix-3/packages/hivecast/bin/hivecast.mjs — the wrapper script
  • projects/matrix-3/packages/hivecast/dist/host-service/cli.js — the host-service CLI
  • projects/matrix-3/packages/hivecast/dist/node_modules/@matrix/mx-cli/ — the matrix CLI

You can run hivecast directly from the checkout:

bash
node projects/matrix-3/packages/hivecast/bin/hivecast.mjs --help

…or symlink it onto your PATH:

bash
sudo ln -sf "$PWD/projects/matrix-3/packages/hivecast/bin/hivecast.mjs" /usr/local/bin/hivecast
sudo chmod +x /usr/local/bin/hivecast

Refreshing a live release after source changes ​

CLAUDE.md documents the rsync recipe for updating an installed .deb from a fresh source build:

bash
cd projects/matrix-3
pnpm --filter @matrix/mx-cli build
pnpm --filter @open-matrix/host-control build
pnpm --filter @open-matrix/host-service build
pnpm --filter hivecast build
rsync -a --delete packages/hivecast/bin/hivecast.mjs \
  /home/ubuntu/hivecast/releases/hivecast-0.1.24/lib/node_modules/hivecast/bin/hivecast.mjs
rsync -a --delete packages/hivecast/dist/host-service/ \
  /home/ubuntu/hivecast/releases/hivecast-0.1.24/lib/node_modules/hivecast/dist/host-service/
rsync -a --delete packages/hivecast/dist/node_modules/@open-matrix/host-control/ \
  /home/ubuntu/hivecast/releases/hivecast-0.1.24/lib/node_modules/hivecast/dist/node_modules/@open-matrix/host-control/
rsync -a --delete packages/hivecast/dist/node_modules/@matrix/mx-cli/ \
  /home/ubuntu/hivecast/releases/hivecast-0.1.24/lib/node_modules/hivecast/dist/node_modules/@matrix/mx-cli/

This is the standard dev-loop refresh pattern — only operators with the source checkout will use it.

Option C — macOS / Windows installers ​

The build scripts exist:

  • projects/matrix-3/packages/hivecast/scripts/build-macos-pkg-installer.js
  • projects/matrix-3/packages/hivecast/scripts/build-windows-msi-installer.js

They are not yet a regular release artifact. Today, on macOS and Windows, use Option B (source-checkout build) and run hivecast via node. Tracked in launch readiness.

Verifying the install ​

bash
hivecast --help

Should print the help text from hivecast.mjs:432-457, starting with:

HiveCast Host commands:
  hivecast install [--no-start] [--root <root>] [--http-port <port|0|auto>]
  hivecast start [--root <root>] [--http-port <port|0|auto>]
  ...

If you don't see that, see Troubleshooting → Host not running.

See also ​

Source: projects/matrix-3/packages/hivecast/scripts/build-deb-installer.js (the .deb build), projects/matrix-3/packages/hivecast/bin/hivecast.mjs (the wrapper), projects/matrix-3/packages/hivecast/package.json (build scripts), and the CLAUDE.md refresh recipe.