Hosting Gateway

Appearance

Logs ​

The gateway is a Matrix runtime. Its logs follow the standard host-service log layout. There is no gateway-specific log file.

Log locations ​

Local install ​

<host-home>/logs/host.stdout.log         # host-service supervisor stdout
<host-home>/logs/host.stderr.log         # host-service supervisor stderr
<host-home>/logs/runtimes/<runtime-id>.stdout.log
<host-home>/logs/runtimes/<runtime-id>.stderr.log

The gateway's runtime ID is typically RUNTIME-HOST-SYSTEM-GATEWAY-HTTP or similar. Find the exact ID with:

bash
node projects/matrix-3/packages/hivecast/bin/hivecast.mjs runtimes --home /tmp/matrix-home

systemd-managed Host ​

bash
journalctl -u hivecast-host.service -f

hivecast-host.service aggregates host-service stdout/stderr; specific runtime logs (including the gateway) are still under <host-home>/logs/runtimes/. systemd carries only the supervisor's stream.

Docker container ​

docker compose logs hivecast-host -f (or whatever the compose service is named). Inside the container, <host-home>/logs/runtimes/ still exists.

Log format ​

Today the gateway logs are unstructured text from console.log / console.error calls. Each runtime's stdout/stderr is captured as-is by host-service.

Note: Per CLAUDE.md Rule 9.4, packages should use actorLog() for bus-native logging instead of console.log. The gateway predates that rule for some of its diagnostic output. Migration is in-progress in WORKSTREAMS/package-structure/.

What to look for ​

Successful startup ​

[host-http-runtime] Listening on 127.0.0.1:3100
[system.gateway.http] mounted
[system.gateway] children: http (mounted)

Common error signatures ​

Log lineMeaning
EADDRINUSE: address already in use 127.0.0.1:3100Another process owns the port; check hivecast status
MatrixHttpAssetEndpointActor requires packageName, appName, and distDir propsAsset endpoint mounted with missing config; the runtime starting it has wrong webapp metadata
Asset response exceeded relay limit of 10485760 bytesA package asset is >10 MB
gateway.http.request only supports GET and HEADA non-GET/HEAD request hit /apps/<appName>/...
Gateway actor has no Matrix contextInternal: actor is being called before bootstrap completed

Following a request ​

To trace a single request end-to-end:

bash
# Watch the gateway's stderr (most error output goes here)
tail -F <host-home>/logs/runtimes/RUNTIME-HOST-SYSTEM-GATEWAY-HTTP.stderr.log

# Watch the package's runtime to see the asset endpoint side
tail -F <host-home>/logs/runtimes/RUNTIME-HOST-CHAT.stderr.log

There is no per-request correlation ID surfaced in logs today. Adding one is in the operability backlog.

What's NOT in the gateway logs ​

  • HTTP access logs (e.g. nginx-style "GET /apps/chat/ 200"). The current gateway does not emit access logs. Caddy in front does, configured per Caddyfile.
  • NATS subject traces. Bus-level subjects are captured by NATS itself if the operator enables NATS tracing; the gateway doesn't surface them.
  • Health-probe noise. /healthz requests are not logged; that's intentional, as monitoring would otherwise drown the log.

See also ​

Source: Logs land in <host-home>/logs/runtimes/ per the host-service log layout. The gateway runtime is no different from any other runtime in this respect.