What is Edge?

Edge is a full local control surface for one Matrix Device. Per P1.44, it is structurally and functionally identical to the matrix-web cloud shell, with only the auth/identity boundary differing. Every paired Device runs Edge — it is part of the base install profile.

When you install Matrix on a laptop, workstation, server, container, VM, or appliance, Edge ships with it as the package @open-matrix/matrix-edge. Open it at http://127.0.0.1:3100/apps/edge/ and you see your full namespace — every Device the user owns (online and offline), every runtime, every mount, every package, every app route, plus local-only diagnostics that the cloud cannot show.

Edge is not a degraded shell

The single most common misconception about Edge is that it is a "lighter" or "simpler" version of the cloud dashboard. It is not. Edge:

• Sees all Devices in the user's namespace, not just this one.
• Renders all five registries (Devices / Runtimes / Mounts / Packages / App Routes) with the same drill-down behavior the platform shell uses.
• Consumes the same shared shell primitives as matrix-web (HiveCastTopNav, AppRouteCard, RuntimeHostCard, RoutePlanPanel, ReadinessBadge, etc., per P1.22c).
• Adds local-only superpower views (raw Host logs, process info, state-dir browser, NATS server status) that the cloud cannot show because the cloud is not the Device.

The asymmetry between Edge and matrix-web is the auth/identity boundary, full stop — not the feature set.

The closed list of allowed differences

These are the only things matrix-web has that Edge does not have:

1. Cloud OAuth login flow. Edge uses local-owner mode (loopback) or a paired-browser session; identity comes from <host-home>/credentials/hivecast-link.json, not from clicking "Sign in with Google."
2. Device-pairing creation flow. Pairing tokens come from the cloud; Edge can show the existing Devices but does not initiate new pairings. (Edge can hand off to matrix-web with an explicit deep link.)
3. Account-level admin. Multi-namespace switching, account billing, account subscription, account deletion — these are platform-level, cloud-only.
4. Cloud-only legal/compliance surfaces. Terms of service acceptance, GDPR data-export, account-deletion request — platform-mediated.

Anything else matrix-web has, Edge has.

What Edge does (today and target state)

Today's Edge core (implemented)

• Probes local service liveness and reachability.
• Reads pair link state (routeKey, publicNamespace, spaceId from bootstrap).
• Reads installed apps and their routes (currently through /api/apps; migrating to system.catalog per P1.43).
• Reads runtime presence (currently through /api/identity/runtime-summary; migrating to system.runtimes).
• Renders app cards with route-plan diagnostics.
• Renders endpoint diagnostics for debugging.

P1.44 target state (in progress)

• All Devices in the user's namespace (not just local), with online/offline status, "open Edge on this Device" deep links, and click-through to per-Device drill-downs.
• All five registries rendered with the same data and behavior as matrix-web's dashboard.
• Bus-native data sources (no /api/apps consumers in matrix-edge/src/).
• Working filter pills on the Mounts strip: Apps / Services / Feeds / Components / Agents / Proxies (per P1.37 vocabulary).
• Shared shell primitives instead of bespoke edge-navbar/edge-shell (per P1.22c finding 5).
• Local diagnostics section (logs, processes, state-dir, NATS status) clearly separated from the registry views.

Where the code lives

projects/matrix-3/packages/matrix-edge/
├── matrix.json          ← appName: "edge", routePrefix: "/apps/edge/"
├── package.json
└── src/
    ├── main.ts          ← entry point + UI orchestration
    ├── edge-model.ts    ← data model + probes
    ├── styles.css       ← visual styling (HiveCast-parity per P1.22c)
    └── index.html       ← root HTML

main.ts is the entry point. Today it composes a view from HTTP probes against the local Host; per P1.43 the data sources are migrating to bus invocations against system.catalog, system.devices, system.runtimes, and system.registry.

What Edge is NOT

• Not a second auth system. No login, no signup, no Google flow. Edge defers to the local Host's system-auth for identity. On loopback the user is the local-client (effective owner) automatically.
• Not a runtime supervisor. The Host Service supervises the runtimes. Edge displays and triggers operations against them; it does not own the supervision loop.
• Not a per-Device-only view. It renders the user's full namespace; "this Device" is highlighted but not the only thing visible.
• Not a degraded subset of matrix-web. See above. The asymmetry is the auth boundary; nothing else.

When you would use Edge

• You just installed Matrix and want to confirm everything is up.
• You want to see all your Devices in one place from your laptop.
• You want to inspect a runtime, a mount, a package, or an app route across your namespace.
• You want to launch one of the local apps (Chat, Director).
• You want to debug a failing app — Edge shows route plans, readiness, and local-only logs the cloud cannot.
• You want to revoke an idle paired Device or pair a new one (Edge shows the deep link to matrix-web for pair creation).

For everyday app use after the first launch, you click directly into Director / Chat. Edge is the control surface, not the destination.

See also

• Edge vs Platform Admin — the auth-boundary distinction in detail.
• Local host view — how Edge models local Host data today.
• Device ownership — who can view and modify what.
• Local Dashboard / Runtime status — runtime card details.
• Device Management / Pair — pairing this Device.

Source: projects/matrix-3/packages/matrix-edge/src/main.ts and edge-model.ts are the entire UI today. matrix.json declares the package metadata. WORKSTREAMS/loose-ends/items/P1.44-edge-full-local-control-surface.md is the normative full-parity spec; P1.43 requires bus-native data; P1.22c tracks the visual-parity slice; P1.37 defines the five registries.