Runtime Host

Appearance

Stop runtime ​

matrix down <target> asks the Host to stop one supervised runtime. The Host translates the target to a runtimeId, sends a graceful shutdown through the runtime's controlMount, and falls back to signals if the graceful path fails.

CLI surface ​

matrix down <runtime-id|package|mount>
matrix down <runtime-id|package|mount> --runtime-id <id>
matrix down <runtime-id|package|mount> --timeout <ms>

projects/matrix-3/packages/host-service/src/cli.ts:237-252. The positional argument is matched against:

  • An exact runtimeId.
  • A packageRef (e.g. @open-matrix/chat).
  • A logical mount (e.g. chat — first segment of any localMounts entry).
  • A package basename or metadata.target.
  • A webapp.appName.

Resolution rules live in resolveRuntimeStopTarget and runtimeStopTargetAliases (cli.ts:517-561). If multiple live runtimes match, the Host refuses with an explicit list.

What "stop" does ​

MatrixHostService.stopRuntimeProcess (matrix-host-service.ts:848-880):

  1. Sanitize runtimeId. Look up the in-memory managed-process map; if the Host did not start this pid, refuse — the caller is talking to the wrong Host.
  2. Mark the record status: "stopping" and write it.
  3. Try graceful shutdown (_requestRuntimeShutdown, matrix-host-service.ts:895-916): invoke runtime.shutdown on the controlMount over NATS with a 2s timeout. Wait up to 5s for the child to exit on its own.
  4. If graceful failed, send SIGTERM (stopChildProcess, matrix-host-service.ts:1705-1724). Wait 2s. If the child still has not exited, SIGKILL.
  5. Write the final record: status: "stopped", stoppedAt: now, updatedAt: now. Close the stdout/stderr streams.

The graceful step matters: a runtime that has open WebSocket clients, JetStream consumers, or browser sessions can hang up cleanly when asked. A SIGTERM-only path leaks resources and is a last resort.

Examples ​

bash
# By runtime id (exact).
matrix down RUNTIME-HOST-LOCAL-ABC123-CHAT

# By package ref.
matrix down @open-matrix/chat

# By logical mount (first segment).
matrix down chat

# By webapp app name.
matrix down inference-settings

Stopping vs unregistering ​

matrix down stops a running runtime. The on-disk runtime.json record remains; if that record had startup: "auto", the next Host start would respawn it. To prevent that, edit the record (or use a future runtime.update op) to set startup: "manual" first.

There is no matrix unregister today. To fully retire a runtime:

bash
matrix down <id>
rm -rf <home>/runtimes/<sanitized-runtime-id>/
rm -rf <home>/logs/runtimes/<sanitized-runtime-id>/
rm -f  <home>/runtime-env/<sanitized-runtime-id>.environment.json

The on-disk layout is the source of truth; the supervisor reads it on every start.

What stop does NOT do ​

  • Does not stop runtimes started by other Hosts (different <home>).
  • Does not stop unmanaged processes — even a process listed in a runtime.json is only managed if its pid was spawned by this Host process. After a Host restart, an old runtime that the Host is now re-supervising is matched up via runtimeProcessIdentityMismatchReason (matrix-host-service.ts:1107-1131) — commandline + cwd compared against the record. A divergence marks the record stale rather than letting matrix down accidentally signal an unrelated pid.
  • Does not block on out-of-band cleanup. The runtime is responsible for its own JetStream consumers, sockets, etc. The Host's job is to ask, wait briefly, and signal.

See also ​