What is HiveCast?

HiveCast is docker-for-actors, packaged as a single workstation/server install. The user model maps directly onto Docker:

Docker world	HiveCast
Image (`nginx:1.27`)	Package (`@open-matrix/chat`)
`docker pull`	`hivecast install`
`docker run`	`hivecast up`
`docker stop`	`hivecast down`
`docker logs`	`journalctl -u <unit>` (a unified `hivecast logs` is target state)
`docker ps`	`hivecast runtimes`
`docker engine`	the local Matrix Host (a Node process, supervisor)
Container name (`--name foo`)	Deployment Instance name (`--instance-name foo`) — see P1.42 for the target multi-instance model

The substrate underneath is a typed pub/sub/RPC fabric (NATS). Every actor declares accepts / emits / streams, has a Space-rooted bus address, and is discoverable through the catalog. HiveCast is the install that ships those primitives to a normal machine.

What an install lays down

One hivecast install gives a Host:

a supervised local Host process (the hivecast-host systemd unit, or hivecast start in dev)
a bundled NATS broker as an independent sibling process (the hivecast-nats systemd unit, or a sibling spawn in dev)
the system actor set (system.runtimes, system.registry, system.devices, system.auth, host.control)
the HTTP gateway plus the matrix-web and matrix-edge shells, served on a single port (default 3100)
a small set of bundled webapps wired up out of the box: Director, Chat, Inference Settings, FlowPad, Smithers
a hivecast CLI for lifecycle and pairing, plus a matrix CLI for package authoring and execution

The full default runtime list lives in the wrapper itself at projects/matrix-3/packages/hivecast/bin/hivecast.mjs lines 28-39:

const hostDefaultRuntimeTargets = [
  { target: 'system', runtimeKey: 'SYSTEM', autoStartPriority: 0 },
  { target: '@open-matrix/host-control', runtimeKey: 'HOST-CONTROL', autoStartPriority: 2 },
  { target: '@open-matrix/system-gateway-http', runtimeKey: 'GATEWAY', autoStartPriority: 5 },
  { target: '@open-matrix/matrix-web', runtimeKey: 'WEB', serve: true, autoStartPriority: 10 },
  { target: '@open-matrix/matrix-edge', runtimeKey: 'EDGE', serve: true, autoStartPriority: 15 },
  { target: '@open-matrix/director', runtimeKey: 'DIRECTOR', serve: true, autoStartPriority: 20 },
  { target: '@open-matrix/chat', runtimeKey: 'CHAT', serve: true, autoStartPriority: 25 },
  { target: '@open-matrix/inference-settings', runtimeKey: 'INFERENCE-SETTINGS', serve: true, autoStartPriority: 30 },
  { target: '@open-matrix/flowpad', runtimeKey: 'FLOWPAD', serve: true, autoStartPriority: 35 },
  { target: '@open-matrix/smithers', runtimeKey: 'SMITHERS', serve: true, autoStartPriority: 40 },
];

After hivecast install, every entry in that list is registered as a supervised runtime with startup: auto and restart: always. A subsequent hivecast start (or a system reboot, with the .deb install) brings them all up.

Status — multi-package runtimes are target state. Today the substrate runs one package per runtime. The target shape is multiple packages per runtime with declared per-package isolation in matrix.json (shared / process / worker / vm); the runtime honors the declaration. See P1.40. User-facing CLI verbs (hivecast up, hivecast down) are forward-compatible.

What an install gets you, end-to-end

After hivecast install completes successfully:

You can	Reach it at
Open the platform shell (matrix-web)	`http://127.0.0.1:3100/apps/web/`
Open this Device's full control surface (matrix-edge)	`http://127.0.0.1:3100/apps/edge/`
Open Director (the runtime topology UI)	`http://127.0.0.1:3100/apps/director/`
Open Chat	`http://127.0.0.1:3100/apps/chat/`
Open FlowPad	`http://127.0.0.1:3100/apps/flowpad/`
Inspect Host status	`hivecast status`
List supervised runtimes	`hivecast runtimes`
List linked Devices	`hivecast invoke system.devices devices.list '{"includeOffline":true}'`
Browse the actor catalog on this Host	`hivecast invoke system.catalog list '{}'`
Check overall health	`hivecast doctor`

Source: installHostProduct in hivecast.mjs:1511-1539. The default HTTP port comes from the .deb postinst (scripts/build-deb-installer.js:309-310 writes "port": 3100 into the Host config); local installs default the same way through seedHostProductHome.

Bus is authority — HTTP only at boundaries

HiveCast exposes only the HTTP endpoints a browser or external monitor cannot avoid:

/healthz — liveness for external HTTP-only monitoring.
/api/bootstrap and /api/identity/nats-creds — credentials issuance for new browser tabs.
/oauth/... — OAuth provider redirects/callbacks.
/apps/<appName>/<assetPath> — static asset serving.
/nats-ws — the NATS WebSocket upgrade.
(Federation handshake when federation lands; webhooks from external providers.)

Everything else is bus-native. Apps, Devices, Runtimes, Mounts, Packages, AI providers, agent state — they all live as actors on the bus with declared accepts ops. Use matrix invoke system.<actor> <op> '<json>' (or hivecast invoke ... from the wrapper). HTTP read projections of those actors exist for non-bus-aware external clients (CI smoke checks, uptime monitors); they are not the authority. See P1.43 for the closed list of allowed HTTP boundaries.

What an install does NOT give you

Honest framing of present state:

No HiveCast account by default. Installation is purely local; pairing to a HiveCast account is a separate, optional hivecast login --device step.
No inference credentials by default. The bundled inference-settings package is the surface for adding them. Per Rule 4, credentials never leave the local Device.
No browser security boundary between the shell and your workstation. The default install binds to 127.0.0.1 and treats the loopback session as the local owner. Containers automatically switch to 0.0.0.0 (postinst detects /proc/1/cgroup).
No production HiveCast traffic. The two-runtime dev topology (matrix-web as platform shell + matrix-edge as Device shell on the same Host) is self-contained — hivecast.ai is not contacted unless you explicitly run hivecast login --device --cloud https://hivecast.ai.
No multi-user authentication on a fresh local install. auth.mode: 'local-client' is the default for local-owner Hosts; public-session is opt-in and required for any setup that intends to host a browser-based UI for a non-loopback session.

Where this fits in the larger Matrix story

Matrix is the typed-actor substrate; HiveCast is the first big provider on it — the install path that ships Matrix to a normal workstation, plus the cloud platform at https://hivecast.ai. The substrate-versus-vertical split is load-bearing: HiveCast is one vertical (one of several), and the substrate is built so that other people can ship their own verticals against the same primitives. The two CLIs reflect the user / author split:

hivecast — Host lifecycle, cloud pairing, a small set of operational verbs that delegate to the local Host.
matrix — package authoring, building, testing, publishing, and direct package execution against an arbitrary Host (via @matrix/mx-cli).

This split is documented inside the wrapper's own help text on hivecast.mjs:454:

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

See HiveCast vs Matrix for more.

What is HiveCast? ​

What an install lays down ​

What an install gets you, end-to-end ​

Bus is authority — HTTP only at boundaries ​

What an install does NOT give you ​

Where this fits in the larger Matrix story ​