Chat

Appearance

Run ​

matrix.json declares Chat as a hybrid package with runtime.entry pointing at dist/runtime/index.js. Host Service runs that runtime; the gateway serves the browser side from dist/browser/.

Daemon-hosted (the production path) ​

bash
matrix up @open-matrix/chat --home /tmp/matrix-home --serve \
  --runtime-id CHAT --env hivecast --startup auto --restart always

What this does:

  1. Host Service writes <host-home>/runtimes/RUNTIME-...-CHAT.json with the package, env, and lifecycle policy.
  2. Host Service spawns the runtime process pointing at dist/runtime/index.js.
  3. The runtime calls createHostManagedChat({ services: { runtime: <provided> } }).
  4. mountHostManagedChatActors registers the 9 chat.* actors via runtime.createSupervised.
  5. With --serve, Host Service binds the package's dist/browser/ at /apps/chat/.
  6. NATS WebSocket bridge is registered. The browser connects via /nats-ws.

Standalone-connected (embedded) ​

When another runtime wants to embed Chat (e.g., a custom platform shell), it can call createStandaloneConnectedChat(transport, overrides, services) directly with a caller-supplied ITransportAdapter. See Developer Guide: runtime integration.

Standalone-local (no bus) ​

createStandaloneLocalChat() is for tests and demos. It creates an in-memory transport, binds Local* services, and renders Chat into the page with no external bus. Not used in production.

Run via two-runtime topology ​

For a worker container running both platform-role and edge-role shells (per CLAUDE.md "Two-Runtime Dev Topology"):

bash
hivecast install --home /tmp/matrix-home --no-start
hivecast start --home /tmp/matrix-home --no-default-runtimes

matrix up @open-matrix/matrix-web  --serve --port 5001 --runtime-id WEB  ...
matrix up @open-matrix/matrix-edge --serve --port 5002 --runtime-id EDGE ...
matrix up @open-matrix/chat        --serve --port 5003 --runtime-id CHAT ...
matrix up @open-matrix/agents              --runtime-id AGENTS    --startup auto --restart always
matrix up @open-matrix/inference           --runtime-id INFERENCE --startup auto --restart always

Browser:

  • http://127.0.0.1:5001/apps/chat/ — via platform shell.
  • http://127.0.0.1:5002/apps/chat/ — via edge shell.

Both heartbeat to the same local system.devices; system.agents and system.inference are shared.

Stopping ​

bash
matrix down CHAT

Or hivecast down CHAT. Either tears down the runtime process, the gateway binding, and the NATS subscriptions.

Restart policies ​

--restart accepts:

  • always — restart on any exit.
  • on-failure — restart on non-zero exit.
  • no — never restart.

For Chat, always is appropriate: a crashed Chat runtime drops the user's connection, and an unrestarted runtime means the page can't reconnect.

Auto-start ​

--startup auto makes hivecast start (the supervisor restart) bring Chat back up. Without it, the runtime record exists but is dormant until manually matrix up'd.

Per-runtime port assignment ​

--port 0 or --port auto lets the OS pick a port. The gateway then proxies /apps/chat/ to that port. The actual port appears in the runtime record (<host-home>/runtimes/RUNTIME-...-CHAT.json) and in the hivecast runtimes output.

For dev predictability, pin a port (e.g., --port 5003).

See also ​

Source: projects/matrix-3/packages/chat/matrix.json, chat/src/runtime/create-host-managed-chat.ts:48-121, CLAUDE.md "Two-Runtime Dev Topology".