Chat

Appearance

Install ​

Chat is one of the default packages a fresh Host installs.

Default hivecast install ​

hivecast install --home <host-home> lays out the Host home, drops bundled NATS, generates host.json, seeds the global package store, and registers default runtimes. Per CLAUDE.md "First 10 Minutes":

The default install spawns these runtimes automatically: system, host-control, system-gateway-http, matrix-web (with --serve), matrix-edge (with --serve).

The Chat runtime is not in that default list as of 2026-05-05; on a fresh install you bring Chat up explicitly. The chat package itself is in the seeded package store, but its runtime is not auto-started.

Bringing up Chat ​

After hivecast install completes:

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

Or via mx-cli:

bash
matrix up @open-matrix/chat --home /tmp/matrix-home --serve

That registers a runtime record under <host-home>/runtimes/RUNTIME-...-CHAT.json and starts the runtime via Host Service. The runtime mounts the 9 chat.* actors (per matrix.json components[]) and serves the browser bundle at /apps/chat/.

Verifying the install ​

bash
hivecast runtimes

Expect a CHAT entry with actorCount > 0 and lastHeartbeat recent.

bash
matrix invoke chat $introspect '{}'

Should return the root actor's accepts (including chat.status) and confirm the runtime is reachable.

bash
curl -fsS http://127.0.0.1:3100/apps/chat/ | head -3

Should return HTML for Chat's index.html. (HTTP 200 alone is not proof of cognitive readiness — see troubleshooting.)

Companion packages ​

Chat needs:

  • @open-matrix/agents — for system.agents.
  • @open-matrix/inference — for system.inference.
  • A provider driver — @open-matrix/driver-anthropic, driver-openai, or driver-ollama.
  • @open-matrix/factotum — for credential resolution.

If any are missing, Chat will load but fail at the first prompt with the dependency-probe error message documented in inference dependency.

File layout produced ​

After install + up:

<host-home>/
├── host.json
├── credentials/
│   ├── hivecast-install.json
│   └── (link record after pairing)
├── runtimes/
│   ├── RUNTIME-...-SYSTEM.json
│   ├── RUNTIME-...-HOST-CONTROL.json
│   ├── RUNTIME-...-CHAT.json          ← from `matrix up @open-matrix/chat`
│   └── ...
└── logs/runtimes/
    └── RUNTIME-...-CHAT.log

The runtime record holds the package version, mount, env, port (if --serve), startup mode, and restart policy.

Reinstalling / upgrading ​

Chat is idempotent: re-run matrix up with the same --runtime-id and Host Service rewrites the record and restarts. Or matrix down <runtime-id> and matrix up again.

When the package is updated in the global package store (hivecast install --no-start after rebuilding), the next runtime restart picks up the new version.

See also ​

Source: projects/matrix-3/packages/chat/matrix.json, chat/package.json, CLAUDE.md "Host Service / Docker-NPM parity dev loop", and projects/matrix-3/packages/hivecast/bin/hivecast.mjs:28-39 (default runtimes list).