Matrix Package Lifecycle

Appearance

Folder-backed source ​

"Folder-backed source" means: the runtime is loading code directly from a working directory in your repo, not from a copy under <MATRIX_HOME>/packages/.../node_modules/<name>/. This is the fastest iteration mode and the one Run in place gives you by default.

When the runtime is folder-backed ​

A runtime is folder-backed in any of these cases:

  1. You ran matrix run . (or mx run .) inside the package directory.
  2. You ran matrix up <path-to-package-dir> against a Host. The resolver in host-service/src/cli.ts:resolvePackageTarget accepts an absolute or relative directory path; if the path exists, the Host uses that directory.
  3. You ran mx install <local-folder> with no copy step (see Installing → Install from local folder for the actual copy-mode install does — folder-backed is the non-install case).

Each of these uses the source dist/ directly. Edit + rebuild + restart picks up changes.

When it is not ​

A runtime is not folder-backed when:

  • It was started by name (matrix up @open-matrix/chat). Host Service resolves names to the package store under <MATRIX_HOME>/packages/.
  • The Host was installed via hivecast install, which seeds the bundled package store. Those copies sit under <host-home>/packages/system/node_modules/ and <host-home>/packages/global/node_modules/ — see packages/hivecast/bin/hivecast.mjs:205-216:seedBundledHostPackages.

Fast iteration recipe ​

The deployless inner loop:

bash
cd projects/matrix-3/packages/<my-pkg>
$EDITOR src/...
pnpm build
matrix run . --env dev
# Ctrl+C, edit, rebuild, restart

Three things to remember:

  1. Always pnpm build between edits. Tests and runtime use dist/.
  2. The embedded NATS in .matrix/dev.environment.json runs in process. Killing the runner kills it.
  3. runtime.root and runtimeId come from the env file, not from any Host config. There is no Host involved.

Folder-backed against an already-running Host ​

You can supervise a folder-backed package inside a running Host:

bash
hivecast start --home /tmp/matrix-home
matrix up /abs/path/to/projects/matrix-3/packages/<my-pkg> \
  --env hivecast --home /tmp/matrix-home

host-service/src/cli.ts:145-235 builds a startSpec whose packageDir is the absolute path you passed. The Host writes a runtime record under <host-home>/runtimes/<runtimeId>.json referencing that absolute path; the runner process imports runtime.entry from there.

This is useful when:

  • You want the Host's gateway (port 3100) to route to your folder- backed runtime under /apps/<appName>/.
  • You want logs aggregated under <host-home>/logs/runtimes/<runtimeId>.stdout.log.
  • You want system.runtimes to know about your runtime so other packages can talk to it.

Caveats ​

  • Build pollution. A folder-backed runtime sees what's in dist/ at startup time. Subsequent rebuilds do not auto-reload; restart the runtime.
  • Path stability. Don't move or rename the package directory while a Host is supervising it. The runtime record stores the absolute path; rename and restart breaks.
  • Workspace dependencies. pnpm workspaces use symlinks under node_modules/. Rebuilds of dependencies update the symlinked dist/ immediately, but your runtime won't see them until you restart.

See also ​

Source: host-service/src/cli.ts:resolvePackageTarget is the piece that decides folder-backed vs name-resolved at up time.