Routes

The gateway recognizes a fixed set of URL grammars, dispatched in a precise order. Earlier matches win — that is how /healthz is reserved before any app can claim it.

Every route below is classified against the substrate's closed list of allowed HTTP boundaries (see P1.43):

• Boundary — on the closed list. Permanent.
• Projection — read-only view of a bus actor for non-bus-aware external clients (CI scripts, third-party monitors). Internal substrate consumers MUST use the bus authority.
• Migrating — currently a projection that is being retired or relabelled.

Pages

• App routes — /apps/<appName>/..., the default app surface.
• Space routes — public-namespace and Space path (formerly routeKey) paths.
• Device routes — target state; not implemented today.
• Asset routes — branding, favicon, and other static assets.
• API compatibility routes — /api/* projections and the boundary credential endpoints.
• Route resolution — how a parsed route becomes an actor call.

Dispatch order

#	Path	Handler	Class	Bus authority
1	/healthz	onHealth	Boundary	n/a (liveness)
2	/	onRootRedirect	Boundary	n/a
3	/api/identity/bootstrap	onBootstrap	Boundary	issues credentials
4	/api/identity/nats-creds	onNatsCreds	Boundary	issues credentials
5	/oauth/<provider>/callback	onOauthCallback	Boundary	system.auth
6	matchesPlatformSurface(path)	onPlatformSurface	Mixed	varies
7	/api/apps	onApps	Migrating (projection of system.catalog)	system.catalog
8	/api/config	onConfig	Projection	system.gateway.http.config
9	/nats-ws	onNatsWsPlainHttp (or upgrade)	Boundary	n/a
10	/favicon.ico, /manifest.json, /branding/*	onBrandingAsset	Boundary	static
11	/edge or /edge/...	302 → /apps/edge/...	Boundary	n/a
12	/<publicNamespace>/<appName>/...	onPublicNamespaceWebapp	Boundary	system.gateway.http
13	/<spacePath>/<appName>/...	onRouteKeyWebapp	Boundary	system.gateway.http
14	/<email>/<appName>/...	onExplicitAuthorityWebapp	Boundary	system.gateway.http
15	/apps/<appName>/...	onWebapp	Boundary	system.gateway.http
16	/api/status	onStatus	Migrating (projection of system.runtimes)	system.runtimes
17	/api/host/stop	onStop	Migrating	host.control
18	/api/runtimes (GET/POST)	onRuntimes / onRuntimeRegister	Migrating	system.runtimes
19	/api/runtimes/start	onRuntimeStart	Migrating	host.control
20	/api/runtimes/stop	onRuntimeStop	Migrating	host.control
21	otherwise	onNotFound	n/a	—

The dispatch loop is MatrixHostHttpGatewayServer._dispatch in projects/matrix-3/packages/system-gateway-http/src/http-listener.ts.

Status: migration in progress. Endpoints marked Migrating still serve compatibility projections. Internal substrate consumers (matrix-web dashboard, navbar, catalog, setup wizard, matrix-edge, agents, proof scripts) MUST migrate to the named bus authority. New code never calls these endpoints; it calls the bus actor.

Source: projects/matrix-3/packages/system-gateway-http/src/http-listener.ts, projects/matrix-3/packages/system-gateway-http/src/http-routing.ts, P1.43.