Matrix Package Lifecycle

Appearance

Running ​

Once a package is installed and a Host is up, the Running stage is where the package becomes a supervised process. The hivecast and matrix binaries share the supervision surface; they both delegate to Host Service.

mx run and mx up share a body ​

This is intentional design. mx run and mx up call the same factory loader against the same runtime construction code; the only difference is whether the Host registers the runtime for auto-restart and persistence across Host restarts.

CommandWhat it doesSupervision
matrix run <pkg>Foregrounds one package as a Matrix runtimeTied to the terminal; exits when you Ctrl-C
matrix up <pkg>Same body; additionally writes <host-home>/runtimes/<id>/runtime.json so the Host auto-restarts itSurvives Host restarts; respects --restart and --startup policies

Same code path, different lifecycle. Use mx run for one-shot foreground work (debugging, demos, ad-hoc tools); use mx up to register a runtime under the Host.

bash
# Foreground — same body, no Host registration.
matrix run @open-matrix/chat --env dev

# Supervised — same body, Host registers it.
matrix up @open-matrix/chat --env hivecast --runtime-id CHAT --startup auto --restart always

Pages ​

  • hivecast up — start a runtime that loads a package
  • hivecast down — stop a runtime
  • Logs — where runtime logs live and how to read them
  • Health — runtime lifecycle states; how to see them
  • Verify — confirming a runtime is actually serving
  • Update — replacing a running runtime with a newer version
  • Rollback — target state — undoing a bad update

hivecast vs matrix ​

The hivecast wrapper is the user-facing CLI for HiveCast Hosts. hivecast up, hivecast down, hivecast invoke are documented in the wrapper's help text (packages/hivecast/bin/hivecast.mjs:432-457) and delegate to the underlying host-service CLI.

matrix up and matrix down are the same code (the matrix binary is the bundled mx-cli and host-service supervisor). Use whichever matches your context:

ContextCommand
HiveCast install (production-style)hivecast up / hivecast down
Bare workspace (no HiveCast wrapper)matrix up / matrix down

The two are not separate features. They are the same supervisor; the wrapper only fronts the same calls.

Multi-package runtimes (target shape) ​

Today, matrix up <package> creates one runtime per package. The substrate target shape is multi-package runtimes: a package's matrix.json declares runtime.isolation, and matrix up can group shared-isolation packages into one runtime by substrate role.

bash
# Today: one runtime per package, ~12 runtimes after a default install.
matrix up @open-matrix/chat
matrix up @open-matrix/director

# Target (P1.40-a): co-tenant shared packages into one runtime.
matrix up @open-matrix/chat @open-matrix/director \
  --runtime-id USER-APPS

Status: target state — multi-package runtimes (P1.40-a). When P1.40-a lands, matrix up <pkg-a> <pkg-b> succeeds when both declare shared; fails with a clear error when one declares process. Default hivecast install groups packages by substrate role automatically. See P1.40.

Hosts vs runtimes ​

A Host is the supervisor process. A runtime is a child process the Host supervises that has loaded one or more packages.

Host Service (supervisor)
├── runtime: RUNTIME-HOST-...-CONTROL-PLANE  → @open-matrix/system + system-gateway-http + agents + inference-catalog
├── runtime: RUNTIME-HOST-...-USER-APPS      → @open-matrix/chat + director + flowpad + smithers + inference-settings
├── runtime: RUNTIME-HOST-...-WEB-SHELL      → @open-matrix/matrix-web
└── runtime: RUNTIME-HOST-...-EDGE           → @open-matrix/matrix-edge

That is the target shape. Today's shape is one runtime per package.

Bringing a Host up: hivecast install and hivecast start. Adding a runtime to an already-up Host: hivecast up. Bringing a Host down: hivecast stop. Removing a runtime from an up Host: hivecast down.

This site covers up, down, logs/health/verify/update/rollback. For install/start/stop/status/doctor, see docs-runtime-host and the HiveCast docs.

Operating through the bus ​

Day-to-day "what's running, what's healthy, restart this" lives on the bus, not on HTTP. Use matrix invoke:

bash
matrix invoke system.runtimes runtimes.list '{}'
matrix invoke system.runtimes runtimes.get  '{"runtimeId":"RUNTIME-..."}'
matrix invoke host.control host.runtime.restart '{"runtimeId":"RUNTIME-..."}'
matrix invoke host.control host.status '{}'

Inventory and control questions go to the named bus actors, not to gateway HTTP endpoints. See P1.43.

See also ​