Edge / User Admin

Appearance

Edge / User Admin ​

This documentation covers Matrix Edge — the local-Device control surface that ships with every Matrix install.

Motivation ​

Edge exists because the substrate's promise is that every Device you own is a full control surface, not just a worker that the cloud talks down to. When you sit at a paired Device, you should be able to see what is running, manage runtimes, inspect mounts, and operate your Space without round-tripping through the cloud dashboard for routine work. Edge is structurally the same surface as the cloud platform shell — same registries, same primitives, same operations — and the only thing it deliberately leaves to the cloud is what genuinely needs cloud-side identity, like OAuth login, pairing-token generation, and account-level admin. Edge is not a degraded subset of the cloud shell; the asymmetry is the auth boundary, full stop. These docs are for you if you operate a Device, debug a local runtime, or want to manage your Space from the machine you are sitting in front of.

What Edge is ​

Edge is a full local control surface, structurally and functionally identical to the matrix-web cloud shell, with only the auth/identity boundary differing.

That sentence is normative. It is the ruling from P1.44. Edge is not a "lite" version of the cloud dashboard. It renders the same five registries (Devices, Runtimes, Mounts, Packages, App Routes), shows all Devices in the user's namespace (not just local), exposes the same diagnostics, and uses the same shared shell primitives the cloud platform shell uses. The asymmetry between Edge and matrix-web is the auth/identity boundary, full stop.

The closed list of things matrix-web has that Edge does NOT have:

  1. Cloud OAuth login flow (Edge uses local-owner mode or a paired-browser session).
  2. Device-pairing creation flow (cloud generates the pairing token).
  3. Account-level admin (multi-namespace switching, billing, account subscription, account deletion).
  4. Cloud-only legal/compliance surfaces (terms acceptance, GDPR data-export).

Anything else matrix-web shows, Edge shows. If a feature exists in matrix-web that doesn't fall into this closed asymmetry list, it MUST exist in Edge — failing that test is a regression of P1.44.

Where Edge fits in the whole ​

Matrix is a typed pub/sub/RPC substrate; HiveCast is a vertical that runs on it. The cloud platform at https://hivecast.ai and the local Edge dashboard are two clients of the same set of bus actors (system.devices, system.runtimes, system.registry, system.catalog, system.packages). They differ in where they run, who they authenticate, and what subset of those actors they can see — not in how the data flows or what operations exist.

Edge is bus-native. Per P1.43, Edge reads system.devices / system.runtimes / system.registry / system.catalog directly over NATS. The HTTP endpoints Edge probes today (/api/apps, /api/identity/runtime-summary) are projections being migrated to bus calls; the migration is tracked in P1.43 Step 4. New code paths must use the bus.

Every paired Device runs Edge ​

@open-matrix/matrix-edge is part of the base install profile. Every hivecast install provisions Edge by default; every paired Device runs it. This is policy, not implementation detail — see P1.44's "Default install policy" section. Removing Edge from the default install reopens P1.44.

Five-minute orientation ​

bash
# Install + start a Host. Edge is in the default runtime list.
hivecast install --home /tmp/matrix-home
hivecast start --home /tmp/matrix-home

# Open Edge.
#   http://127.0.0.1:3100/apps/edge/

# Edge reads bus actors directly. The same calls work from any operator
# session on the Device:
matrix invoke system.devices devices.list '{"includeOffline":true}'
matrix invoke system.runtimes runtimes.list '{}'
matrix invoke system.catalog list '{}'

If Edge doesn't show your other Devices, that is a P1.44 regression to file — Edge MUST show all Devices in the user's namespace.

What this docs domain covers ​

Overview ​

What Edge is, the parity-with-cloud rule (P1.44), the local-host view it renders, and the Device-ownership model.

Local Dashboard ​

What the user sees when they open Edge: the five registries, the local app launcher, runtime status, packages, logs, Device pairing status. Plus the local-additive surfaces (raw Host logs, process info, NATS server status) that augment the cloud view because the user is on the Device.

Device Management ​

User actions on a Device: pair to a HiveCast account (handed off to the cloud as the cloud generates the pairing token), disconnect, rename, check health, troubleshoot.

Reference ​

Bus actor ops Edge invokes, the HTTP closed-list boundaries (browser bootstrap, asset serving, NATS WebSocket), configuration, diagnostics.

Visual and functional parity rules ​

Per P1.22c and P1.44, Edge consumes the same shell primitives as matrix-web (HiveCastTopNav, AppRouteCard, RuntimeHostCard, RoutePlanPanel, ReadinessBadge, DegradedTargetPanel, RecoveryActions). Post-extraction, Edge does not maintain any divergent dashboard rendering. The current parallel edge-navbar/edge-shell packages are a transitional fork tracked by P1.22c.

If Edge's dashboard rendering diverges from matrix-web's — different fonts, different layout, different filter pills, different empty states — that is a regression. Burden of proof is on divergence.

Local-additive surfaces (allowed beyond matrix-web) ​

Edge can render diagnostics matrix-web cannot, because the user is sitting at the Device:

  • Raw Host logs viewer (<host-home>/logs/runtimes/).
  • Local process info (ps of Host runtimes, memory usage).
  • Local state-dir browser (<host-home>/runtimes/, <host-home>/instances/).
  • NATS server status / JetStream usage.

These are augmentation, not replacement. They live in a clearly-labeled "Local diagnostics" section. They do not replace any matrix-web feature.

Sister docs ​

Status of the parity work ​

Today's Edge implements the core — local service status, pair link state, app catalog, runtime summary, route plan diagnostics. The full P1.44 surface (all Devices in the namespace, all five registries with shared primitives) is in progress; pages in this section mark target-state sections explicitly.

Source: projects/matrix-3/packages/matrix-edge/ is the entire package. WORKSTREAMS/loose-ends/items/P1.44-edge-full-local-control-surface.md is the normative full-parity spec. WORKSTREAMS/loose-ends/items/P1.22c-edge-hivecast-visual-parity.md tracks the visual/structural-parity slice already in flight. WORKSTREAMS/loose-ends/items/P1.37-dashboard-registries-ontology.md defines the five registries Edge must render. WORKSTREAMS/loose-ends/items/P1.43-http-api-reduction-bus-is-authority.md requires bus-native data sources.