HiveCast Product

HiveCast is docker-for-actors. The mental model maps cleanly:

Docker / npm	HiveCast
docker pull <image>	hivecast install <package>
docker run <image>	hivecast up <package>
docker stop <container>	hivecast down <runtime>
docker logs <container>	journalctl -u <unit> (a unified hivecast logs is target state)
docker ps	hivecast runtimes
docker engine	the local Matrix Host (a Node process)

Motivation

HiveCast exists to turn the Matrix substrate from an idea into something a person can install in five minutes. One CLI on a laptop, workstation, server, container, or VM gets you a supervised Host, a local NATS broker, the system actor set, the browser shells, and a curated package set — a personal AI runtime with real hands on the machine instead of a chat box behind a wall. Without HiveCast the substrate is a protocol; with it, anyone can pair a Device to a Space, run packaged actors, and have an agent that acts on real systems. These docs are for you if you are installing HiveCast on your own hardware, operating it for a team or organization, or evaluating what it actually looks like to ship the substrate to a normal machine.

The thing you publish is a Package; the thing that runs is a supervised Runtime; the thing that hosts Runtimes is a Host. HiveCast is the product that wraps a Host and gives a workstation, server, container, or VM the full set of pieces in a single install:

• a supervised local Host process (hivecast-host.service)
• a bundled NATS broker as a sibling process (hivecast-nats.service)
• the system actor set on the bus (system.runtimes, system.registry, system.devices, system.auth, host.control)
• the gateway plus the matrix-web and matrix-edge browser shells served on a single HTTP port (default 3100)
• a hivecast CLI for lifecycle and pairing, plus a matrix CLI for package authoring and direct package execution

Where HiveCast fits in the whole

Matrix is a typed pub/sub/RPC substrate — a federated bus where every Feed, Service, and Component is the same primitive: a typed actor with a Space-rooted address, declared accepts / emits / streams, and a discovery surface. Matrix is the substrate; HiveCast is one vertical on top of it. HiveCast is the first big provider on the substrate — the install path that ships Matrix to a normal machine, plus the cloud platform that runs at https://hivecast.ai.

This documentation covers HiveCast as the end-user product: install, pair, run packages, troubleshoot, and look up the file/port/config layout. Substrate-level docs (the Matrix protocol, package authoring, the actor contract, registry mechanics) live in sibling docs packages (docs-matrix, docs-sdk, docs-package-lifecycle, docs-registry). The cloud platform side (Spaces, multi-Device admin, OAuth) lives in docs-platform. The local Device dashboard lives in docs-edge. The Device pairing reference lives in docs-devices.

See WORKSTREAMS/thesis/THESIS.md Parts 1 (docker-for-actors framing), 5 (verticals), and 9 (what HiveCast charges for).

Five-minute quickstart

# 1. Install the .deb (Linux) or build from source — see Quickstart.
sudo dpkg -i hivecast_<version>_amd64.deb

# 2. Start the Host. The .deb does this on install via systemd; in a checkout:
hivecast install --home /tmp/matrix-home
hivecast start --home /tmp/matrix-home

# 3. Verify the Host is up.
curl -fsS http://127.0.0.1:3100/healthz | jq .
hivecast status --home /tmp/matrix-home
hivecast runtimes --home /tmp/matrix-home

# 4. Open the browser shells.
#    http://127.0.0.1:3100/apps/web/    ← matrix-web (account/platform shell)
#    http://127.0.0.1:3100/apps/edge/   ← matrix-edge (this Device's full control surface)

# 5. Inspect what is running on this Device, on the bus.
hivecast invoke system.devices devices.list '{"includeOffline":true}'
hivecast invoke system.catalog list '{}'
hivecast invoke system.runtimes runtimes.list '{}'

The bus is the authority. /api/bootstrap, /healthz, /oauth/..., /nats-ws, and /apps/<name>/<asset> are the only HTTP endpoints that exist for browsers and external monitors; everything else (apps, devices, runtimes, mounts, packages, AI providers) lives behind matrix invoke ... against the bus. See P1.43 for the closed list of allowed HTTP boundaries.

Conceptual map — what's in this docs domain

Section	Why you'd read it
Overview	What HiveCast actually is, the docker-for-actors framing, local-vs-cloud, glossary, and how HiveCast relates to Matrix the substrate.
Quickstart	Six pages, run in order, from "I have nothing" to "Director loads in a browser."
CLI	Every hivecast subcommand, exit codes, and how hivecast up / hivecast down map to docker-style verbs.
Local Device	Operating one Host: install, service install, lifecycle, logs, runtime records, uninstall.
Cloud Account	Linking this Device to a HiveCast account, Spaces, hosted runtimes (target state), the auth boundary.
Troubleshooting	Symptom-driven recipes for the most common failure modes.
Reference	Config files, env vars, filesystem layout, ports, service-manager integration, compatibility matrix.

Reading order

If this is your first time:

1. What is HiveCast?
2. Local host vs cloud platform
3. Quickstart

If something is already broken:

1. Troubleshooting → Host not running
2. CLI → exit codes and diagnostics
3. Reference → filesystem layout

Vocabulary the rest of these pages use

User-facing terms only. Internal-only names (installId, hostId, host.json, configName, routeKey) appear only when these docs are explaining the data model — never in CLI prose.

Term	Meaning
Device	A linked compute participant — laptop, workstation, server, VM, container, phone, appliance — running HiveCast. The user-facing product term.
Space	The user's durable public-identity unit. Contains the Space path, owner, and authority root.
Space path	The user-facing public Space route handle (e.g. alt.stories.ghost-stories.funny). Goes in URLs as /<spacePath>/<appName>/.
Package	The thing published and installed (@open-matrix/<name>). Analogous to a Docker image or npm package.
Runtime	A Node process supervised by the Host that mounts one or more packages onto the bus.
Mount	A bus path where an actor lives (e.g. chat.preferences).
Bus	The NATS substrate carrying typed pub/sub and request/reply.

Sister docs

• Matrix protocol — actors, subjects, mounts, the substrate model.
• Package lifecycle — author → build → publish → install → run.
• Edge / User Admin — this Device's full local control surface.
• Device Management — pairing, ontology, schemas.
• HiveCast Platform — the cloud platform side.

Authoritative sources behind this documentation

Topic	Source path
Product framing and sequencing	WORKSTREAMS/thesis/THESIS.md
Docker-for-actors model + multi-package runtimes	WORKSTREAMS/loose-ends/items/P1.40-docker-for-actors-multi-package-runtimes.md
HTTP boundary rule (bus is authority)	WORKSTREAMS/loose-ends/items/P1.43-http-api-reduction-bus-is-authority.md
CLI dispatch and help text	projects/matrix-3/packages/hivecast/bin/hivecast.mjs
Host config schema, runtime record schema, status schema	projects/matrix-3/packages/host-service/src/types.ts
Default Host home layout	projects/matrix-3/packages/host-service/src/host-paths.ts
.deb installer (systemd units, journald cap, postinst)	projects/matrix-3/packages/hivecast/scripts/build-deb-installer.js
Device pairing spec	WORKSTREAMS/product-launch/HIVECAST-DEVICE-ENROLLMENT-SPEC.md
Device terminology (canonical)	CLAUDE.md "Device Link contract" + "Identity lifecycle"

When the documentation and the code diverge, the code is what is; the docs are what should be. Fix the docs.

Source portability: every page on this site is plain CommonMark + GFM, per WORKSTREAMS/product-consolidation-and-documentation/PORTABILITY-RULES.md. No MDX, no Vue, no framework-specific admonitions.