Hosting Gateway

Appearance

Device routes ​

Status: target state, NOT IMPLEMENTED. There is no /device/<deviceSlug>/... URL grammar parser in the current gateway. This page documents what such a grammar might look like and how it would relate to existing routes.

Why this isn't in the code ​

Today, every URL maps to either:

  • An app route (/apps/<appName>/...)
  • A Space route (/<routeKey>/<appName>/... or /<publicNamespace>/<appName>/...)
  • An explicit-authority route (/<email>/<appName>/...)
  • A platform endpoint (/api/..., /healthz, etc.)

A user has only one Device or many Devices, and a Device's apps are addressable through the user's authority root. There has not been a need to URL-address "this app on this Device" because:

  • Users typically own one Device.
  • When users own multiple Devices, the authority root already disambiguates.
  • Cross-Device routing is handled at the relay layer (HiveCast Edge selects the right runtime origin behind the scenes), not the URL.

What target-state device routes might look like ​

If the future requires explicit per-Device URLs (for example, "open this shell on the workstation, not the laptop"), a candidate grammar is:

/device/<deviceSlug>/<appName>/<asset-path>

With:

  • deviceSlug: stable address-safe management projection key under system.devices.<deviceSlug> (per the discovery metadata spec).
  • Same appName and asset-path rules as /apps/<appName>/.

The handler would resolve deviceSlug through system.devices to a runtime origin and then issue a relay similar to explicit-authority routes.

This is target state. It has not been specified in any active workstream.

Today's substitute ​

To address an app on a specific Device today, callers can:

  1. Use the explicit-authority URL grammar with the user's email if the Device has been linked under that authority root.
  2. Use Director or another runtime UI to invoke a specific runtime by runtimeId.
  3. Use mx-cli with --runtime-id <id> for invoke operations.

None of these provide a per-Device URL prefix that the browser can use as a permanent bookmark, but they cover the operator-tooling case.

See also ​

  • Space routes
  • App routes
  • WORKSTREAMS/runtime-environment-multi-instance/ — where multi-Device topology is being designed

Source: No parseDeviceRoute function exists in projects/matrix-3/packages/system-gateway-http/src/http-routing.ts. This page is target-state placeholder content.