Matrix Package Lifecycle

Appearance

Config explain ​

Status: present state, partial. There is no dedicated mx config explain or matrix run --explain command in the current code. This page documents the four CLI surfaces that together let you reconstruct what a runtime will see, plus a target-state outline for a future unified command.

Present-state surfaces ​

mx config — CLI config ​

bash
mx config get registry
mx config set registry https://registry.example.com/api/packages/...
mx config list
mx config reset

Source: packages/mx-cli/src/commands/config.ts. The CLI config is the per-user config used by mx publish/mx install/mx search. Today it has one key: registry. Default is https://registry.hivecast.ai/api/packages/open-matrix/npm/ (packages/mx-cli/src/utils/config-store.ts:DEFAULT_PACKAGE_REGISTRY).

The CLI config file lives at one of:

  1. --config-file <path> if explicitly passed
  2. $MATRIX_CLI_CONFIG if set
  3. <MATRIX_HOME>/cli-config.json (default ~/.matrix/cli-config.json)

mx info <packageName> — installed package metadata ​

bash
mx info @open-matrix/chat --packages-dir /tmp/matrix-home/packages/global

Prints the package directory, whether it has matrix.json, and the package version it resolves. Source: packages/mx-cli/src/commands/info.ts.

mx validate — manifest sanity check ​

bash
cd projects/matrix-3/packages/<my-pkg>
mx validate
mx validate --json | jq .diagnostics

Reports manifest validation errors. Useful for confirming that the manifest you're running matches the one the validator expects.

Direct file inspection — environment files ​

bash
cat .matrix/dev.environment.json | jq .

The file is the literal source of truth for runtime.root, NATS mode, runtime id, and HTTP port when running with --env dev. There is no merge step at this layer; what's in the file is what the runner sees.

Direct file inspection — host.json ​

bash
cat /tmp/matrix-home/host.json | jq .transport

host.json is the Host-level transport/auth/storage config. Edits here are picked up only on hivecast stop/hivecast start.

How the layers compose ​

For a runtime started by matrix run . --env dev:

┌──────────────────────────────┐
│ matrix.json                  │ package identity, components,
│  └─ config.{schema,defaults} │ defaults+schema for package config
└──────────────────────────────┘
              │
              ▼
┌──────────────────────────────┐
│ .matrix/dev.environment.json │ wire root, NATS, http port,
└──────────────────────────────┘ runtimeId
              │
              ▼
┌──────────────────────────────┐
│ env vars (config.providers)  │ per-process overrides
│ + file path from $MATRIX_*   │
│ + system.config service      │
└──────────────────────────────┘
              │
              ▼
       what the actor sees

Read it bottom-up to debug: if an actor sees an unexpected value, walk the providers in order, then the env file, then the defaults, then the schema for shape mismatches.

Target state — one command ​

A future mx run --explain (or mx config explain) would:

  1. Resolve the manifest, env file, and providers in order.
  2. Print the merged config that an actor would receive.
  3. Annotate each value with its source layer.
  4. Validate against config.schema and report any drift.

This is filed as a quality-of-life follow-up; not in code today. Use the four surfaces above as the workaround.

A practical debugging recipe ​

When an actor misbehaves:

  1. mx validate — confirm the manifest is structurally valid.
  2. cat matrix.json | jq .config — see what providers are declared.
  3. cat .matrix/<env>.environment.json — see the wire/runtime identity.
  4. env | grep MATRIX_<PKG>_ — see what the env provider would pick up.
  5. mx info <packageName> (when running against a Host) — confirm which copy of the package the runtime resolved.
  6. hivecast invoke system.config '<op>' '{"namespace":"@open-matrix/<pkg>"}' if you use a config service — confirm what it returns.

See also ​

Source: projects/matrix-3/packages/mx-cli/src/commands/config.ts for mx config; packages/mx-cli/src/commands/info.ts for mx info; packages/mx-cli/src/commands/validate.ts for mx validate.