Chat

Appearance

Logs ​

Three places to look.

1. Per-runtime files ​

<host-home>/logs/runtimes/RUNTIME-...-CHAT.log — stdout/stderr of the chat runtime process. Useful for early-startup errors before NATS is connected.

bash
tail -f /tmp/matrix-home/logs/runtimes/RUNTIME-*-CHAT.log

2. journalctl (systemd-managed Hosts) ​

For native installs (hivecast install --service), the supervisor runs as a systemd service:

bash
journalctl -u matrix-host-edge.service -f

Includes both Host Service supervisor logs and (subordinate) the chat runtime's stderr. Per CLAUDE.md:

Logs are read with journalctl -u <service> for systemd-managed Hosts or via the per-runtime files under <host-home>/logs/runtimes/.

3. system.observability.logging (canonical) / system.logging (compat) ​

The bus-native logging path. Chat actors use actorLog() (per CLAUDE.md Coding Standards #4 — no console.log); those calls land on system.observability.logging if that actor is mounted.

To query:

bash
matrix invoke system.observability.logging logging.query \
  '{"source":"chat","limit":50}'

Or via Director's Ops Feed at /apps/director/, filtered to kind: 'log' and source: chat (see Director's Logs page).

What you'll see during normal operation ​

A healthy Chat runtime log shows:

[matrix-runtime] starting runtime CHAT
[matrix-runtime] mounted: chat (MatrixChatApp)
[matrix-runtime] mounted: chat.security-realm (ChatSecurityRealmService)
[matrix-runtime] mounted: chat.topic-claims (ChatTopicClaimService)
[matrix-runtime] mounted: chat.identity (ChatIdentityProxy)
[matrix-runtime] mounted: chat.conversation (ChatConversationProxy)
[matrix-runtime] mounted: chat.component-library (ChatComponentLibraryProxy)
[matrix-runtime] mounted: chat.preferences (ChatPreferencesProxy)
[matrix-runtime] mounted: chat.session-state (ChatSessionStateProxy)
[matrix-runtime] mounted: chat.export (ChatExportService)
[matrix-runtime] registered with system.runtimes (RUNTIME-...-CHAT)
[matrix-runtime] heartbeat sent

Subsequently, periodic heartbeat lines and per-prompt activity lines.

Common log entries to investigate ​

  • [MatrixChat] No bound runtime config and no explicit runtime-mode declaration were found. — bindChatServices was not called before the page tried to read the bound config. Root cause: bootstrap path wired wrong.
  • [MatrixChat] Stream timeout — no events received in <ms> ms — system.agents accepted the prompt but no $activity frames returned. Check system.agents and system.inference health.
  • Prompt rejected by system.agents for ...: { ok: false, ... } — system.agents returned an explicit failure ACK.

Browser console ​

The browser side logs to the DevTools console. Chat does not pipe console logs to the runtime. For production debugging where the user can't open DevTools, all the action lives on the runtime side.

Log rotation ​

Per-runtime files grow. Host Service does not currently rotate them. Operators are expected to use logrotate or a similar tool. For systemd-managed installs, journalctl rotation handles the supervisor log.

See also ​

Source: <host-home>/logs/runtimes/ layout per CLAUDE.md, projects/matrix-3/packages/host-service/src/ (log handling), Chat's actorLog() usage in src/.