HiveCast vs Matrix

HiveCast and Matrix are not competing products. They are two layers of the same system, exposed through two CLIs whose responsibilities are intentionally divided.

One sentence each

• Matrix is the actor framework and package model. The matrix CLI (from @matrix/mx-cli) is for package authors and developers: scaffold, build, test, publish, and run packages against any Host.
• HiveCast is the product wrapper that turns Matrix into something a normal user can install. The hivecast CLI is for end users, operators, and platform admins: install/start/stop the local Host, pair to a HiveCast account, supervise runtimes.

Decision table

You want to…	Use	Notes
Install Matrix on a workstation	hivecast install	One-shot. Brings up Host + NATS + system actors + bundled webapps
Start an installed local Host	hivecast start
Stop a running local Host	hivecast stop	Also stops the sibling NATS process
Bring a package up as a supervised runtime	hivecast up <pkg> (or matrix up)	hivecast delegates to host-service for up/down/invoke
Stop a runtime	hivecast down <id|pkg|mount>	Same
Call into a mounted actor	hivecast invoke <mount> <op> [json]	Wrapper for host-service invoke; same effect
Pair this Device to a HiveCast account	hivecast login --device --cloud <url>
Inspect the Device link	hivecast whoami / hivecast link-status
Disconnect from cloud	hivecast logout	See Cloud Account → Login for --all etc
Scaffold a new package	matrix init <name>	The matrix CLI is for authoring
Build a package	cd <pkg> && pnpm build (or matrix build)	Builds happen in package space
Publish a package	matrix publish	Pushes to the configured Gitea-backed npm registry
Run a package against a Host (any Host)	matrix run <package-or-path> --home <host-home>	Direct execution; useful in dev
Inspect Host status without hivecast	matrix status --home <host-home>	The two CLIs share the host-service backend

The wrapper itself prints the boundary at the bottom of hivecast --help (line 454 of hivecast.mjs):

Package commands live under the matrix binary: matrix install, matrix up, matrix down.

Why two CLIs

The product wrapper deliberately keeps a narrow surface. From CLAUDE.md Rule 1:

Host Service supervises processes only. HTTP lives in @open-matrix/system-gateway-http; auth/session/namespace/device approval lives in @open-matrix/system-auth; runtime lifecycle control lives through @open-matrix/host-control; package logic lives in packages.

Translated to CLI terms: hivecast ships the Host product (lifecycle + pairing + the small set of operational verbs that delegate to the running Host). matrix ships the package toolchain (authoring, build, publish, run-anywhere). The same person may use both, but the responsibilities don't overlap.

What hivecast actually delegates to host-service

The wrapper's delegation list is one line in hivecast.mjs:425:

if (['init', 'status', 'runtimes', 'up', 'down', 'invoke'].includes(command)) {
  return process.argv[2] ? process.argv.slice(2) : ['status'];
}

These six subcommands are pure pass-throughs to the host-service CLI:

• hivecast init → host-service init
• hivecast status → host-service status
• hivecast runtimes → host-service runtimes
• hivecast up <pkg> → host-service up <pkg> --home <home>
• hivecast down <id> → host-service down <id> --home <home>
• hivecast invoke <mount> <op> → host-service invoke <mount> <op> --home <home>

In other words, anything done via hivecast for a running Host can also be done via matrix (or host-service directly) against any Host home. This matters for advanced setups where one machine operates multiple Hosts.

What hivecast does NOT delegate

These commands are wrapper-direct (handled inside hivecast.mjs, not forwarded):

• Lifecycle: install, start, stop, seed, doctor (because they manage the Host process itself)
• Cloud pairing: login, connect, whoami, logout, link-status (forwarded to mx-cli rather than host-service — they need access to credential files, not a running Host)
• Operator scripts: operator <cmd> (require the source checkout)
• Internal: bootstrap-default-runtimes (called from the systemd ExecStartPost hook)

See CLI command overview for the full inventory.

What if I install Matrix without HiveCast?

You can — pnpm --filter @matrix/mx-cli build and use matrix directly. You'll lose:

• the bundled NATS sibling (you have to provide your own broker)
• the bundled package store (you have to populate it from the workspace)
• hivecast.ai pairing (no cloud-account UX)
• the .deb / systemd integration

In dev, that's fine. For an end-user install on a workstation, the hivecast wrapper is the supported path.

See also

• What is HiveCast? — what one install gets you.
• Product model — Environment / Package / Runner / Host as separate concerns.
• CLI command overview — every hivecast subcommand inventoried.

Source: projects/matrix-3/packages/hivecast/bin/hivecast.mjs line 425 (delegation list) and lines 432-457 (help text); projects/matrix-3/packages/mx-cli/src/cli.ts (matrix CLI implementation).