Logs

Status: target state. Edge has no log viewer today. The Endpoint Diagnostics panel shows probe outcomes (not log lines). For runtime logs, you tail files on the Device.

What Edge shows today

Edge's only log-shaped surface is the Endpoint Diagnostics panel (main.ts:747-758):

• One row per probe (/healthz, /api/bootstrap, /api/auth/me, /api/identity/runtime-summary, /api/apps).
• Endpoint, status code, state, duration, error message if any.
• A "Refresh diagnostics" button.

This is sufficient for "is the local service up" diagnostics. It is not a log viewer.

Where logs actually live

Per HiveCast Platform / Reference / Database ownership:

<host-home>/logs/runtimes/<runtime-id>.log

One file per runtime. Each runtime's actorLog writes structured records. The supervisor writes its own logs to <host-home>/logs/host-service.log.

Tail logs from the Device

# All runtimes
tail -f <host-home>/logs/runtimes/*.log

# One runtime
tail -f <host-home>/logs/runtimes/system-gateway-http.log

# Filter for errors
tail -f <host-home>/logs/runtimes/*.log | jq 'select(.severity=="error")'

# Look at supervisor
tail -f <host-home>/logs/host-service.log

These commands work today. Edge does not surface them.

Target log viewer

A target Edge log surface would offer:

• Live tail mode — websocket stream, last N lines updating.
• Per-runtime filter — pick which runtimes to include.
• Severity filter — info/warn/error.
• Free text search — substring match.
• Pause/resume for inspection.
• Export to file.

It does not need to be feature-rich; even basic tail-with-filter would be a step up.

Why this isn't already built

Two reasons:

1. Log streaming over the bus. A live tail UI needs a streaming source. actorLog already publishes to bus topics, but Edge does not subscribe. Adding the subscription is small; doing it well (back-pressure, ring buffer) is more work.
2. Privacy / scope. Edge runs as local-owner; showing logs from other principals' runtimes (in a multi-tenant single Device) requires scope thinking. Today single Device = single principal, so the issue is moot.

Operational logs vs audit logs

Per HiveCast Platform / Security / Audit logs, the platform's logs today mix operational (debug, info, error) with auditable security events (login, pair, revoke). Edge's target log viewer would be operational only — security audit is a platform-admin concern, not an end-user concern.

What to do when something goes wrong

Without an Edge log viewer, the procedure is:

1. Identify the broken runtime from Edge's Runtimes card or the app launcher.
2. SSH to the Device (or open a terminal locally).
3. Tail the runtime log:

   tail -50 <host-home>/logs/runtimes/<runtime-id>.log

4. Look for error severity lines, stack traces, recent restarts.
5. If not obvious, also tail the supervisor log:

   tail -50 <host-home>/logs/host-service.log

For deep debugging, see HiveCast Platform / Admin / Operations: Inspect runtime.

Headless Devices

A headless Device (server, container) typically has no Edge UI accessible — it is reached via SSH only. Logs are at the same paths. The lack of a log UI hurts most for paired browser users who don't have SSH access to their own paired Device.

See also

• Runtime status — health surface.
• Reference: Diagnostics — Endpoint Diagnostics panel detail.
• HiveCast Platform / Admin / Dashboard: Logs — platform log target.
• HiveCast Platform / Security / Audit logs — pipeline status.

Source: projects/matrix-3/packages/system-platform/src/actorLog.ts for actorLog. projects/matrix-3/packages/matrix-edge/src/main.ts:747-758 for the Endpoint Diagnostics panel.