Matrix Package Lifecycle

Appearance

Verification ​

A deployment profile says what the Host should be running. Verifying the deployment is the act of comparing that intent to reality. Use the four-question recipe.

The four questions ​

Q1. Is the Host process up? ​

bash
hivecast status --home /tmp/matrix-home
curl -fsS http://127.0.0.1:3100/healthz | jq .

hivecast status reports the supervisor's stored status and pidfile. /healthz is the gateway's liveness check. Both must answer.

Q2. Are all expected runtimes registered? ​

bash
hivecast runtimes --home /tmp/matrix-home
ls /tmp/matrix-home/runtimes/

Compare:

  • The on-disk record set under runtimes/
  • The live runtime list reported by hivecast runtimes

A record on disk that doesn't appear live means the supervisor either failed to start it (check stderr log) or startup: "manual" keeps it dormant.

Q3. Are the runtimes actually serving? ​

bash
matrix invoke system.runtimes runtimes.list '{}' --home /tmp/matrix-home
matrix invoke chat conversation.list '{}' --home /tmp/matrix-home
matrix invoke system.devices devices.list '{}' --home /tmp/matrix-home

Each invoke confirms the actor at the named mount answers a real op, not just that its host process is alive. CLAUDE.md "END TO END TESTING" — invoking known-good ops on known-good actors is the strongest single-line proof you can do.

Q4. Are the user-visible surfaces working? ​

bash
# 1. Web app loads
curl -I http://127.0.0.1:3100/apps/web/
curl -I http://127.0.0.1:3100/apps/director/
curl -I http://127.0.0.1:3100/apps/chat/

# 2. Open in a real browser, watch console for NATS errors

For HiveCast device-link flows, run the proof script:

bash
node projects/matrix-3/scripts/prove-fresh-device-link.ts \
  --route-key codex-proof-$(date -u +%Y%m%d-%H%M) \
  --cloud https://hivecast.ai

A proof script is the canonical "this still works" evidence — exits 0 when the flow worked, non-zero with output otherwise.

What hivecast doctor adds ​

hivecast doctor --home <home> --json covers static prerequisites (NATS binary present, host.json parses, credentials file present) that don't show up in the four questions. Run it after install or when something looks wrong:

bash
hivecast doctor --home /tmp/matrix-home --json | jq .
hivecast doctor --home /tmp/matrix-home --repair

Source: runHostDoctor in packages/hivecast/bin/hivecast.mjs. See projects/matrix-3/packages/docs-hivecast/content/cli/hivecast-host.md for the full check list.

A repeatable verification script ​

Wrap the four questions in a small script you can run as a "deployment is healthy" check:

bash
#!/usr/bin/env bash
set -euo pipefail

HOST="${1:-/tmp/matrix-home}"
HTTP_PORT="${2:-3100}"

echo "Q1: Host process"
curl -fsS "http://127.0.0.1:$HTTP_PORT/healthz" >/dev/null

echo "Q2: Runtimes registered"
hivecast runtimes --home "$HOST" --json | jq '. | length'

echo "Q3: Bus reachability"
matrix invoke system.runtimes runtimes.list '{}' --home "$HOST" >/dev/null
matrix invoke system.devices devices.list '{}' --home "$HOST" >/dev/null

echo "Q4: Web apps"
for app in web edge director chat inference-settings flowpad smithers; do
  code=$(curl -s -o /dev/null -w '%{http_code}' "http://127.0.0.1:$HTTP_PORT/apps/$app/")
  if [ "$code" != "200" ]; then
    echo "  $app: $code (FAIL)" >&2
    exit 1
  fi
  echo "  $app: 200"
done

echo "OK"

Run it after every install, every refresh, and as part of CI.

What this verification does NOT cover ​

  • Browser-side correctness. curl -I /apps/<name>/ returns 200 but the JS may still fail. Run a real browser session for user-visible flows.
  • Cross-Host federation. This site covers single-Host shape; cross-Host route correctness is platform-side and out of scope.
  • Performance. This is liveness, not throughput.

See also ​

Source: Verification commands wrap projects/matrix-3/packages/host-service/src/cli.ts (status / runtimes / invoke) and packages/hivecast/bin/hivecast.mjs (doctor). Proof scripts under projects/matrix-3/scripts/.