Matrix Package Lifecycle

Appearance

Update ​

Updating a running package means replacing its installed version with a newer one and restarting the runtime. The CLI does not have a single mx update command; the supported pattern is down → install --force → up, plus an operator helper that wraps it.

The four-step recipe ​

bash
HOST=/tmp/matrix-home
PKG=@open-matrix/chat
RUNTIME=RUNTIME-HOST-CHAT

# 1. Stop the runtime
hivecast down "$RUNTIME" --home "$HOST"

# 2. Install the new version (registry)
mx install "$PKG" --packages-dir "$HOST/packages/global" --force

# 3. Start the runtime again
hivecast up "$PKG" --home "$HOST"

# 4. Verify
hivecast runtimes --home "$HOST" | jq '.[] | select(.runtimeId=="'"$RUNTIME"'")'
hivecast invoke chat conversation.list '{}' --home "$HOST"

This is what hivecast operator refresh-host-package automates for the "build a local checkout and reinstall it" case.

The operator helper ​

bash
hivecast operator refresh-host-package \
  --package @open-matrix/chat \
  --home /tmp/matrix-home \
  --restart

Source: packages/hivecast/scripts/refresh-host-package.js, registered at packages/hivecast/bin/hivecast.mjs:73-76.

What it does:

  1. Builds the named package in the source checkout.
  2. Removes the old install copy from the Host's package store.
  3. Installs the rebuilt package into the same store slot.
  4. With --restart, stops and starts the runtime supervising the package.

Use it for development; for production updates use the explicit four-step recipe so you can pause between steps to verify.

Update from a folder-backed runtime ​

If the runtime started from a folder path (hivecast up /abs/path/...), you can rebuild and bounce without touching the package store:

bash
cd projects/matrix-3/packages/<my-pkg>
pnpm build
hivecast down <runtimeId> --home <host-home>
hivecast up /abs/path/to/projects/matrix-3/packages/<my-pkg> \
  --env hivecast --home <host-home>

The runtime re-imports runtime.entry from disk on the next start. This is faster than the install-based update but does not exercise the install lifecycle hooks.

Update preserves runtime records ​

Stopping a runtime leaves its record in <host-home>/runtimes/<runtimeId>.json. A subsequent hivecast up with the same --id reuses that record (mounts, supervision policy, runtime mount). You don't have to re-specify --startup auto --restart always on every update.

Schema-evolution considerations ​

CLAUDE.md Rule 9.9: schema evolution is additive only. If the new version of the package adds an op or an event, peers that haven't been updated yet will keep working — they just don't use the new op. If the new version removes or renames an op, peers will break. Don't ship breaking changes without a coordinated deploy plan.

Update vs reinstall vs reload ​

GoalRecipe
Replace the running version with a newer onedown → install --force → up (or refresh-host-package --restart)
Re-deploy the same version after fixing a hook buginstall --force; lifecycle hooks re-run
Refresh code without changing version (folder-backed)down + up against the same path
Refresh config without restartingEdit <host-home>/runtime-env/<runtimeId>.json and ask the runtime to reload (depends on the package)

Errors during update ​

If mx install --force fails, the previous version is restored from the backup (packages/mx-cli/src/commands/install.ts:367-400). The runtime that was just stopped will not auto-start until you fix the issue and re-run install + hivecast up.

If hivecast up fails after a successful install, the new code is present but not running. Check the runtime's stderr log under <host-home>/logs/runtimes/<runtimeId>.stderr.log for the exception.

See also ​

Source: projects/matrix-3/packages/hivecast/scripts/refresh-host-package.js bundles the four-step recipe; the underlying steps are mx install, mx uninstall, hivecast down, hivecast up.