Local routes

Edge calls a small set of HTTP endpoints on the local Host. This page documents the wire shape of each.

Status: present state — HTTP; target state — bus. Per P1.43, the only HTTP endpoints Edge needs in the long run are the closed-list boundaries (/healthz, /api/identity/bootstrap, /api/identity/nats-creds, /oauth/..., /apps/..., /nats-ws, webhooks). The data behind /api/apps, /api/identity/runtime-summary, and /api/auth/me lives in bus actors (system.catalog, system.runtimes, system.auth) — those are the authority. Edge migrates each consumer to bus invocations and the HTTP endpoints become read-only projections for non-bus-aware external clients (CI, third-party monitors). This page documents what the code does today.

/healthz

GET /healthz

Liveness probe. Returns 200 with a JSON body when the gateway is alive.

{
  "ok": true,
  "service": "matrix-host"
}

/api/bootstrap

GET /api/bootstrap

Returns the browser bootstrap. Used by Edge for route key, namespace, principal, transport plan.

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 };
}

/api/apps

GET /api/apps

Returns the installed-webapp catalog.

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?: { id, state, mount, lastError }[];
  artifact?: { freshness, reason, builtAt, gitSha };
}

/api/auth/me

GET /api/auth/me

Returns the calling identity.

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

For an anonymous remote browser: { authenticated: false }.

For a loopback connection: { authenticated: true, localClient: true, principalId: 'host-service' }.

For a paired-browser session: { authenticated: true, principalId: '<owner-id>', principal: { ... } }.

/api/identity/runtime-summary

GET /api/identity/runtime-summary

Returns the runtime/Device summary used by Edge and the dashboard.

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

App-route URLs

Edge composes app launch URLs as:

• /<routeKey>/<appName>/ if linked.
• /apps/<appName>/ if not linked.

Source: edge-model.ts productAppPath and appUrl.

Pairing endpoints

Edge does not call these directly today; the gateway and the CLI use them. They are documented for completeness:

Endpoint	Method	Purpose
/auth/link	GET	Browser pair-flow entry.
/api/devices/enroll/start	POST	Start enrollment (target shape).
/api/devices/enroll/complete	POST	Complete from signed-in browser.
/api/devices/redeem	POST	Device redeems approved enrollment.

Device-side endpoints

Called by host.control from the Device, not from Edge:

Endpoint	Method	Purpose
/_auth/host-link/heartbeat	POST	Heartbeat from paired Device. Bearer token.
/_auth/host-link/credentials/refresh	POST	Refresh device-scoped JWT. Bearer token.

NATS WebSocket

/nats-ws

Same-origin NATS WebSocket. Browser clients connect with a Bus token from /api/nats-jwt.

What Edge does NOT call

• No mutation endpoints.
• No /api/devices/... ops (revoke, etc.) — those happen via the platform shell or CLI today.
• No system-auth POSTs.

Edge is read-only.

See also

• Local host view — how routes feed the data model.
• Diagnostics — Endpoint Diagnostics panel.
• HiveCast Platform / Reference / Platform APIs — platform-side routes (a superset of Edge-relevant ones).

Source: projects/matrix-3/packages/matrix-edge/src/main.ts for the calls. projects/matrix-3/packages/system-gateway-http/src/host-platform-http-surface.ts for the implementation.