Local host view

Edge composes its view from local data sources. This page documents the data model (EdgeModel) and how it is populated today.

Status: present state — HTTP probes; target state — bus invocations. Per P1.43, Edge is migrating its data sources from HTTP projections (/api/apps, /api/identity/runtime-summary) to direct bus invocations against system.catalog, system.runtimes, system.devices, and system.registry. This page describes what the code does today; the migration is in flight.

The EdgeModel

Source: projects/matrix-3/packages/matrix-edge/src/edge-model.ts:101-109.

export interface EdgeModel {
  readonly health: Probe<unknown>;
  readonly bootstrap: Probe<BootstrapPayload>;
  readonly identity: Probe<IdentityPayload>;
  readonly runtimeSummary: Probe<RuntimeSummaryPayload>;
  readonly apps: Probe<AppsPayload>;
  readonly detectedRouteKey?: string;
  readonly detectedRouteKeySource?: string;
}

A Probe<T> is:

interface Probe<T> {
  readonly endpoint: string;
  readonly state: 'checking' | 'ok' | 'unavailable' | 'error';
  readonly status?: number;
  readonly data?: T;
  readonly error?: string;
  readonly durationMs?: number;
}

State semantics:

• ok — HTTP 2xx, parsed body.
• unavailable — HTTP 404 or 405, or skipped because the origin doesn't expose this endpoint.
• error — HTTP 5xx, network failure, or JSON parse error.
• checking — initial state before the probe completes.

The five probes

1. /healthz

Liveness probe. The local Host's gateway returns { ok: true, ... } if the supervisor is up and the gateway is responding. Failure here means "the local service stack is not reachable."

2. /api/bootstrap

Returns BootstrapPayload:

interface BootstrapPayload {
  root?: string;
  addressRoot?: string;
  routeKey?: string;
  publicNamespace?: string;
  canonicalNamespace?: string;
  canonicalRoute?: string;
  spaceId?: string;
  authorityRoot?: string;
  authenticated?: boolean;
  principal?: { principalId, displayName, email };
  transportPlan?: { sessionMode, authMode, wsPath };
}

The bootstrap is what the browser uses to set up the NATS WebSocket connection. Edge reads it for:

• routeKey / publicNamespace / spaceId — pair link metadata.
• authorityRoot — bus root.
• authenticated, principal — identity for the support cards.

3. /api/apps

Returns AppsPayload:

interface AppsPayload {
  apps?: AppEntry[];
}
interface AppEntry {
  appName: string;
  displayName?: string;
  icon?: string;
  description?: string;
  url?: string;
  shells?: string[];
  navOrder?: number;
  packageName?: string;
  packageVersion?: string;
  routePrefix?: string;
  routeKind?: string;
  assetMount?: string;
  origin?: string;
  deploymentInstanceId?: string;
  deploymentInstances?: DeploymentInstance[];
  artifact?: { freshness, reason, builtAt, gitSha };
}

This drives the app launcher and the catalog page. Edge filters out appName === 'web' (the platform shell never appears in the local launcher).

4. /api/auth/me

Returns IdentityPayload:

interface IdentityPayload {
  authenticated?: boolean;
  localClient?: boolean;
  principalId?: string;
  displayName?: string;
  principal?: { id, principalId, displayName, email };
  session?: { sub, localClient };
}

Probed only when the origin is loopback or when the bootstrap shows authenticated. Used for the "local owner" decision and the identity pill.

5. /api/identity/runtime-summary

Returns RuntimeSummaryPayload:

interface RuntimeSummaryPayload {
  authority?: { addressRoot, workspaceRealm };
  authorityRoot?: string;
  requestedRoot?: string;
  effectiveRoot?: string;
  attachedLeafRoots?: unknown;
  registeredRuntimes?: unknown;
  runtimeRoots?: unknown;
  error?: string;
}

Drives the Runtimes support card.

Probe gating

Edge is careful about which probes it calls. The full flow (main.ts:48-96):

const shouldProbeInitialEndpoints = shouldProbeInitialHostEndpoints(hostname);
// /healthz, /api/bootstrap, /api/apps — always for any non-empty hostname.

const shouldProbePrivateEndpoints = shouldProbePrivateHostEndpoints(bootstrap, hostname);
// /api/auth/me, /api/identity/runtime-summary — only when:
//   - hostname is loopback (127.0.0.1, localhost, [::1]), OR
//   - bootstrap returned authenticated: true

This guards against "Edge running on a public preview origin that doesn't expose private endpoints." The probe records state: 'unavailable' with a clear message.

Authority detection

Source: edge-model.ts:255-276.

If bootstrap returns no routeKey, Edge tries to detect one from the hostname:

• If hostname ends with .hivecast.ai, the first label is a candidate routeKey.
• Excluded labels: hivecast, www, registry.
• The detection is for display only — detectedRouteKey is shown with a (detected) marker, never used for actions that require a real route.

Loopback detection

isLoopbackHostname(hostname: string): boolean
// Returns true for 'localhost', '127.0.0.1', '[::1]'.

Used to decide whether the origin is local-owner-eligible.

What "local owner" means

Source: edge-model.ts:221-237.

isLocalOwner(health, identity, hostname) =>
  loopbackHost && sameOriginHealthy
  || identity.localClient === true
  || identity.principal?.principalId === 'host-service'

Local-owner means: the loopback origin is healthy, OR the identity payload explicitly says local-client. It does NOT mean "the user is signed in." A signed-in user at hivecast.ai/<spacePath>/edge/ is paired, not local-owner.

See also

• What is Edge? — role.
• Edge vs Platform Admin — surface distinction.
• Local Dashboard / Runtime status — how the model renders.
• Reference: Local routes — endpoint catalog.

Source: projects/matrix-3/packages/matrix-edge/src/edge-model.ts for the data model. main.ts:48-96 for the probe orchestration.