Edge / User Admin

Appearance

Diagnostics ​

The Endpoint Diagnostics panel is Edge's lowest-level surface. It shows raw probe outcomes for the five HTTP endpoints Edge depends on. This page is the operator's reference for reading the panel.

Where to find it ​

On the Edge dashboard, scroll to "Endpoint Diagnostics" — an expandable details section. Click to expand.

Source: main.ts:747-758 (renderDiagnostics).

What each row shows ​

Per probe (5 total):

<endpoint>           <state>          <pill: ok|warn|bad|neutral>
HTTP <status> in <ms>ms
<error message if any>

Endpoint ​

The path probed (/healthz, /api/bootstrap, /api/auth/me, /api/identity/runtime-summary, /api/apps).

State ​

One of:

  • ok — probe succeeded.
  • unavailable — endpoint returned 404 or 405, or the probe was skipped (origin doesn't expose this endpoint).
  • error — endpoint returned 5xx or the request failed (network error, parse error).
  • checking — initial state, replaced by one of the above.

Status code ​

HTTP status if a response came back. Empty if the request never completed.

Duration ​

Round-trip time in milliseconds.

Error message ​

If non-ok, a short description: "Endpoint returned HTTP 502," "fetch failed," "Skipped because this preview origin..."

Refresh button ​

Below the rows: a Refresh diagnostics button (main.ts:819-824).

Clicking it:

  1. Resets the page to the loading state.
  2. Re-fetches all five probes.
  3. Re-renders.

Useful when:

  • You restarted the local Host and want to verify it came back.
  • You're triaging a transient issue.
  • You want a fresh duration measurement.

What "skipped" means ​

Per main.ts:48-86, Edge gates probes:

  • Initial probes (/healthz, /api/bootstrap, /api/apps) run for any non-empty hostname.
  • Private probes (/api/auth/me, /api/identity/runtime-summary) run only when the origin is loopback OR the bootstrap shows authenticated.

If you're loading Edge from an anonymous public origin (e.g., a preview URL without a session), the private probes are skipped — diagnostics shows them as unavailable with a note: "Skipped because this origin is not presenting local-owner or linked device identity."

This is intentional. Edge does not probe endpoints it can't authenticate against.

Reading common patterns ​

All green ​

Healthy. Local-owner mode confirmed. Apps catalog loaded. Identity resolved. Runtime summary returned.

/healthz red, others mixed ​

The local Host is not running or not reachable. Restart.

/api/bootstrap green, /api/auth/me skipped ​

You're on a public origin without a session. Either sign in to HiveCast, or load Edge from the loopback URL.

/api/apps green but empty body ​

Gateway is up, but no webapp runtimes are registered. See Installed packages troubleshooting.

/api/identity/runtime-summary returns error 503 ​

The supervisor's runtime-summary actor isn't ready. Wait 10 seconds and refresh; if persistent, restart the Host.

Beyond the panel ​

For deeper inspection beyond what the panel shows:

bash
# Curl the same endpoints
curl -i http://127.0.0.1:3100/healthz
curl -i http://127.0.0.1:3100/api/bootstrap
curl -i http://127.0.0.1:3100/api/apps
curl -i -H "Cookie: mx_session=..." http://127.0.0.1:3100/api/auth/me

# Tail supervisor logs
tail -f <host-home>/logs/host-service.log
tail -f <host-home>/logs/runtimes/system-gateway-http.log

These give response body content and full headers — Edge's panel only shows status/duration/error.

Why the panel is plain HTML ​

Per CLAUDE.md Rule 9 (no console.log) and the Vertical Slice Rule, the Endpoint Diagnostics panel is intentionally minimal. It is a debugging surface, not a polished UX. The data is the value.

A target richer view would include:

  • Response body preview.
  • Headers tab.
  • Timing breakdown (DNS, connect, TLS, response).
  • Diff against last probe.

These are not in scope today.

See also ​

Source: projects/matrix-3/packages/matrix-edge/src/main.ts:747-771 for the panel rendering. edge-model.ts for Probe<T> semantics.