HiveCast Product

Appearance

Glossary ​

Definitions used throughout this documentation. Cross-referenced from the rest of the site. When code uses an internal term that differs from product copy, both names are listed and the one to use externally is marked.

Core product terms ​

Device ​

A linked compute participant owned by the user: a laptop, desktop, server, VM, container, phone, or appliance running HiveCast. The user-facing product noun. Internally tracked through system.devices. Every successful hivecast login --device results in one Device in the account's Devices list.

A Device "has runtimes." A Runtime "has actors." A Driver on a Device "exposes resources" that "become actors." Source: WORKSTREAMS/product-launch/HIVECAST-DEVICE-ENROLLMENT-SPEC.md.

Host ​

The supervisor process that manages runtimes on a Device. The product Host implementation is @open-matrix/host-service. One Device today maps to one local install maps to one Host. Future grouping may sit one local Device above multiple Host installs; not in code today.

In product copy, prefer "Device" over "Host." Internal/operational documentation may say "Host" when referring to the supervisor itself.

Host home (<MATRIX_HOME>, <host-home>) ​

The directory containing one Host's persistent state: host.json, runtime records, logs, credentials, the bundled NATS data dir, the package stores. Default ~/.matrix on Linux/macOS or /var/lib/hivecast on a .deb install. Override with --home or MATRIX_HOME=.

See Reference → Filesystem layout.

Package ​

A directory with a matrix.json. Owns code and declares actors. Examples bundled by HiveCast: system, @open-matrix/host-control, @open-matrix/system-gateway-http, @open-matrix/director, @open-matrix/chat. A package is not a runtime; it becomes a runtime when a runner picks it up.

Runner / Runtime ​

The execution unit. One process. Reads one package + one Environment, mounts actors. The product term in operational copy is Runtime (matches the on-disk runtimes/ directory and the system.runtimes actor). Use Runner when emphasizing the architectural role.

Mount ​

The address an actor publishes itself at, e.g. system.devices, chat.conversation, director.http. A package's matrix.json declares its default mounts; hivecast up can override with --mount. Mounts under system.runtimes.<runtime-id>.* are management projections; mounts elsewhere are logical addresses.

Actor ​

A long-lived addressable thing on the bus, with a single mailbox at <root>.<mount>.$inbox. Every actor declares static accepts, emits, streams, state, subscribes, blackboard per the Actor Communication Contract. Actors are mounted by runtimes.

Identity terms ​

Install id (installId) ​

A durable per-install identifier. Stored in <host-home>/credentials/hivecast-install.json. Generated on first hivecast install by ensureHiveCastInstallIdentity (projects/matrix-3/packages/mx-cli/src/utils/hivecast-link-store.ts). Survives reinstalls (idempotent generation). One install on one machine is one installId.

Host id (hostId) ​

A per-link identifier. Stored inside <host-home>/credentials/hivecast-link.json. Generated only after hivecast login --device succeeds, by generateHostId (projects/matrix-3/packages/system-auth/src/host-auth.ts). Internal-only — does not appear in product UI.

Host name (hostName) ​

A mutable human-readable Device label. Set with hivecast login --device --device-name <name> or via the setup flow. Lives in hivecast-link.json. May change without affecting the underlying installId or hostId.

Device slug (deviceSlug) ​

A stable, address-safe management projection key under system.devices.<deviceSlug>. Allocated once by system-auth from hostName, collision-resolved within a principal + Space. Does NOT automatically change when hostName changes.

Display name (displayName) ​

Reserved for principal/user identity. Forbidden as a device field. (See CONSTRAINTS.md C27.)

Device name (deviceName) ​

Forbidden in device contracts because it is ambiguous between label and slug. Use hostName (label) or deviceSlug (key) explicitly.

Authority and Space terms ​

Principal ​

The authenticated account that owns one or more Devices. A principal is identified by an internal id and (today) one canonical authority root.

Space ​

A shared public address that one or more Devices can publish actors into. The user-facing path is the Space path (spacePath), e.g. alt.stories.ghost-stories.funny. Used in URLs as /<spacePath>/<appName>/.

Authority root ​

The internal bus/security/runtime root for a Space or principal, e.g. SPACE.SPC_7F3A9B2C or COM.NIMBLETEC.RICHARD-SANTOMAURO. Derived from the durable Space id (for new Spaces) or from the email (for legacy principals). Never derived from public path text. Source: WORKSTREAMS/loose-ends/items/P1.23f-public-spacepath-authority-root-v2.md.

Address root ​

The public actor address root advertised to browser bootstrap. May coincide with authorityRoot for simple setups.

Wire root ​

The NATS subject prefix used for one Host's local traffic, e.g. COM.OPEN-MATRIX.LOCAL.AUTHORITY. Set in host.json transport.root. Per-runtime override in runtime.json runtimeWireRoot.

Route key (routeKey) ​

A v1 compatibility alias for spacePath. New code/docs/UI says "Space path." The CLI flag --route-key is preserved as a v1 alias.

Public namespace ​

space.<spacePath> — the typed namespace claim. Never appears in user URLs.

Lifecycle terms ​

Local-owner mode ​

Auth mode where the Host trusts the loopback session as the local owner. host.json auth.mode: "local-client". The default for hivecast install. Per CLAUDE.md: "Local owner mode, no HiveCast login required."

Public-session mode ​

Auth mode where the Host accepts external browser sessions, gates them through OAuth, and issues per-session NATS credentials. host.json auth.mode: "public-session". Required for any Host that should serve a non-loopback browser audience (i.e., the hivecast.ai cloud role).

The ceremony that links a local Host to a HiveCast cloud account. The internal API/storage name is Host Link. The user-facing term is Device Link (or just "pairing").

Heartbeat ​

Periodic message from host.control carrying Device inventory + status. Sent over the local bus to system.devices for owner-mode Hosts, or to <cloud>/_auth/host-link/heartbeat for cloud-linked Devices. Validated by auth.hostLink.verifyHeartbeat.

hivecast install vs hivecast start ​

install is the idempotent first-time setup that lays out <host-home> AND (unless --no-start) starts the Host. start only starts an already-installed home. install is safe to re-run; it's the same as start if host.json already exists.

Build / runtime terms ​

Bundled NATS ​

The nats-server binary the wrapper drops into <host-home>/bin/. Started as a sibling process by hivecast start, NOT as a child of host-service. Why: production splits NATS into its own systemd unit (hivecast-nats.service) so host-service restarts don't restart NATS. The dev path matches.

Runtime record (runtime.json) ​

The on-disk authoritative record of one runtime's identity, state, and policy. Lives at <host-home>/runtimes/<runtime-id>/runtime.json. Schema in projects/matrix-3/packages/host-service/src/types.ts:79-96. Read by host-service status and the actor-side system.runtimes projection.

system.devices ​

The product/account-facing linked-Device facade. Exposes devices.list, devices.get, devices.heartbeat, devices.runtimes.list/register. Per CLAUDE.md: "It must not become the public actor namespace."

system.registry ​

Logical mount claims. The actor that adjudicates "which runtime owns mount chat?" One singleton per authority root.

system.runtimes ​

Physical runtime inventory. The actor that exposes the in-memory view of runtimes/*.json. One singleton per authority root.

CLI / wrapper-specific terms ​

Bare verb ​

A hivecast subcommand without a namespace, e.g. hivecast install (vs. the target-state hivecast host install). The current code uses bare verbs throughout. See CLI command overview.

Operator command ​

A hivecast operator <cmd> subcommand that runs a release/deploy script from the source checkout. Listed in hivecast.mjs:40-85. Examples: registry-parity, publish-bootstrap, deploy-release. Not for normal users.

Bootstrap ​

In HiveCast: the systemd ExecStartPost-style step that runs hivecast bootstrap-default-runtimes after hivecast-host.service is healthy. Brings up the default runtime set. Implemented in hivecast.mjs:1414-1462.

In the docs portal world (different sense): the JSON document that the gateway returns to a browser to wire it up to the local Host (subject root, NATS WS URL, principal). Not relevant to CLI users.

See also ​

Source: repo-root CLAUDE.md (Identity lifecycle table); projects/matrix-3/packages/host-service/src/types.ts; projects/matrix-3/packages/system-auth/src/host-auth.ts; WORKSTREAMS/product-launch/CONSTRAINTS.md C27; WORKSTREAMS/loose-ends/items/P1.23f-public-spacepath-authority-root-v2.md.