Package deployments

A package deployment is the act of installing a package on a Device, registering a runtime for it, and supervising it. This page covers what is implemented today and the target deployment-profile model that platform admin work is heading toward.

Present-state deployment model

Today a package is deployed in three steps:

Install — the package's dist/ is placed under <host-home>/.matrix/packages/<package-name>/. For default packages this is done by hivecast install. For ad-hoc packages, mx-cli's matrix install <package-or-path> does it.
Register a runtime — host.control accepts runtimes.declare (or matrix up) to add a runtime record under <host-home>/runtimes/<runtimeId>.json. The record carries package, mount, env, serve (if it's a webapp), startup (auto or manual), restart (always, on-failure, never), and an optional port.
Start — the Host Service supervisor reads runtime records on startup; runtimes with startup: auto come up immediately. Manual ones come up via matrix run <runtimeId> or host.control runtimes.start.

A typical end-to-end:

bash

hivecast install --home /tmp/matrix-home
hivecast start --home /tmp/matrix-home

# Add an extra runtime by hand (most users won't need this — defaults cover the
# usual packages)
matrix up @open-matrix/some-package --serve --port 5050 \
  --runtime-id MY-PKG --env hivecast --startup auto --restart always \
  --home /tmp/matrix-home

Source: projects/matrix-3/packages/host-control/src/index.ts defines the runtimes.* ops on host.control and the runtime record schema. projects/matrix-3/packages/host-service/src/host-state-store.ts persists records.

What gets installed by default

hivecast install (per the wrapper at projects/matrix-3/packages/hivecast/bin/hivecast.mjs:28-39) seeds the bundled package store with:

system (the platform root and system.* actors)
host-control
system-gateway-http
matrix-web (with --serve)
matrix-edge (with --serve)
director
chat
inference-settings
flowpad
smithers

Each gets an auto-allocated port behind the gateway unless --port is pinned. The default install is therefore a complete local Matrix experience plus the platform shell — no extra steps needed for the user-facing apps.

Versioning today

A "version" today is whatever dist/ content was bundled into the install. There is no built-in registry pull; package versions ship with the HiveCast wrapper release. Operators upgrading a Device upgrade the wrapper:

bash

# On the Device
sudo apt install hivecast=0.1.<n>   # or rsync the new release directory
hivecast stop
hivecast start

Target state: A registry-backed pull (Gitea-as-npm) is in WORKSTREAMS/docker-npm-parity/. A Device would pull <package>@<version> from a configured registry, materialize it into the package store, and reload runtimes referencing it.

What "deployment profile" will mean (target state)

Per WORKSTREAMS/docker-npm-parity/ and the runtime-environment-multi-instance workstream, a deployment profile would be:

yaml

profile: production
runtimes:
  - id: WEB
    package: '@open-matrix/matrix-web'
    serve: true
    port: 5001
    startup: auto
    restart: always
    env: hivecast
  - id: EDGE
    package: '@open-matrix/matrix-edge'
    serve: true
    port: 5002
    startup: auto
    restart: always
    env: hivecast

A profile would be:

A first-class record on the platform Host (or on each Device) that supersedes ad-hoc per-runtime config.
Reconcilable: changing the profile triggers a controlled rollout (start new, stop old, gate by health probes).
Versionable: profile revisions are tracked, rollback is one op.
Scoped: a profile can target a single Device, a fleet, an organization, or all paired Devices for a principal.

None of that is implemented today. Profiles, rollouts, gated rollback — all target state. The data model already supports the primitives (runtime records on host.control, the supervisor's reconciler), but the orchestration layer is not built.

How a runtime relates to a Space

Every runtime carries an authorityRoot (its bus root). For runtimes on a paired Device, the authority root is the Space's authorityRoot (the Host Link's). Bus traffic from this runtime flows under the Space's wire prefix.

A Device that owns multiple Spaces would have multiple authority roots represented. The runtime-environment-multi-instance workstream specifies how a single Device can supervise per-Space sub-Hosts cleanly.

Browser webapps vs headless runtimes

Two runtime kinds matter for deployment:

Webapp runtimes declare webapp metadata in their matrix.json: appName, displayName, routePrefix, shells: ['platform' | 'edge']. The gateway serves their dist/ under routePrefix and registers them in /api/apps.
Headless runtimes have no HTTP surface. They mount actors only. Examples: system-inference, system-factotum (when not also serving its UI), driver packages.

matrix.json's webapp.shells field controls which shells render the app:

["platform"] — appears only in the HiveCast platform shell (matrix-web /apps/web/#dashboard).
["edge"] — appears only in the local Edge dashboard catalog.
Both — appears in both.

docs-platform and docs-edge themselves declare shells: ["platform"] (per their matrix.json).

Failure modes worth knowing

Empty runtime record (zero-byte JSON). Caused crash loops historically; hivecast seed (runSeedCommand) now self-heals empty records.
Port collision. A runtime declared with a fixed --port fails to start if the port is taken. --port 0 lets the OS allocate.
Package not in store. The runtime's package field must match an installed package. host.control runtimes.declare does not auto-pull from a registry.
Wrong env. --env hivecast vs --env dev selects different transport defaults; see the env schema work in runtime-environment-multi-instance.

See Reference: Operational runbooks for repair procedures.

Package deployments ​

Present-state deployment model ​

What gets installed by default ​

Versioning today ​

What "deployment profile" will mean (target state) ​

How a runtime relates to a Space ​

Browser webapps vs headless runtimes ​

Failure modes worth knowing ​

See also ​