Edge / User Admin

Appearance

Installed packages ​

Edge surfaces installed webapp packages via the app launcher. It does not surface the full package store, package versions, or package management actions today. This page covers what is shown, what is not, and the present-state CLI workarounds.

What /api/apps returns ​

The platform's HTTP gateway projects installed webapps as a list. Each row carries:

  • appName — short kebab-case name.
  • displayName — human label.
  • icon, description — optional UI metadata.
  • url — preferred launch URL.
  • shells — ["platform"] or ["edge"] or both.
  • navOrder — sort hint.
  • packageName, packageVersion — npm-style identity.
  • routePrefix — base URL prefix on the gateway.
  • routeKind, assetMount, origin — route plan provenance.
  • deploymentInstanceId, deploymentInstances[] — live runtime presence.
  • artifact — { freshness, builtAt, gitSha } build metadata.

Source: edge-model.ts:58-81.

What the launcher renders ​

Source: main.ts:481-504 (renderAppRow).

Each app row shows:

  • App icon badge.
  • Display name.
  • Description / package name.
  • Source label (e.g., installed webapp).
  • Route URL.
  • Runtime label (deploymentInstanceId or not reported).
  • "Open" link.
  • Expandable route plan (per P1.22d).

The catalog page (Hash route #catalog) filters to apps declaring shells: ["edge"] or that omit shell restrictions.

What is NOT shown ​

Things you might expect:

  • Full package store — <host-home>/.matrix/packages/ may have more packages than appear in /api/apps. Headless packages (e.g., system-inference, drivers) don't have webapps and don't show up.
  • Per-package version history — what was installed when, what was upgraded.
  • Package configuration — runtime records, env, port pins.
  • Package install/uninstall actions — Edge has no buttons for install/remove.

CLI workarounds ​

List the full package store ​

bash
ls /tmp/matrix-home/.matrix/packages/
# Or
ls <host-home>/.matrix/packages/

Inspect a package's matrix.json ​

bash
cat <host-home>/.matrix/packages/<package-name>/matrix.json
# webapp metadata, declared actors, dependencies

Inspect runtime records (which packages are running) ​

bash
ls <host-home>/runtimes/
cat <host-home>/runtimes/<runtime-id>.json

Add a runtime for an installed package ​

bash
matrix up @open-matrix/some-package --serve --port 5050 \
  --runtime-id MY-PKG --env hivecast --startup auto --restart always \
  --home <host-home>

Remove a runtime ​

bash
matrix invoke host.control runtimes.remove '{"runtimeId":"MY-PKG"}' \
  --home <host-home>

Route plan diagnostics ​

Per P1.22d, each app row has a "Route plan" expandable. It shows:

  • URL.
  • appName.
  • Route prefix.
  • Gateway (always system.gateway.http).
  • Scope (/<routeKey>/ if linked, local otherwise).
  • Route kind.
  • Runtime id.
  • Package name.
  • Asset source.

When the route plan is missing fields (e.g., no asset source), Edge displays a warning. This is P1.22d proven and live.

Target state ​

  • Add Package action — install a package from the configured registry.
  • Remove Package action — uninstall (with confirmation, since it cascades to runtimes).
  • Per-package detail page — full matrix.json, dependencies, actor inventory, recent log lines.
  • Version selection — pin a specific version for a runtime.
  • Compatibility info — show which packages are known-compatible.

Why packages don't auto-show in Edge ​

A package that exists in <host-home>/.matrix/packages/ but isn't running (no runtime record) is invisible to Edge. Edge depends on /api/apps, which depends on the gateway, which depends on running runtimes registering with system.runtimes and propagating webapp metadata.

To make a package visible:

  1. Verify it has webapp declarations in matrix.json.
  2. Declare a runtime: matrix up @open-matrix/<name> --serve ....
  3. Wait for the runtime to register (~5-30 seconds).
  4. Refresh Edge.

See also ​

Source: projects/matrix-3/packages/matrix-edge/src/main.ts:389-419 (apps card). edge-model.ts:160-190 for the model.