App Hosting

This section is for package authors and operators who want to understand how a Matrix package's browser app actually reaches a browser.

Pages

• Static app packages — the production path: built dist/browser/ served via MatrixHttpAssetEndpointActor
• Runtime-backed apps — apps that have a headless service runtime in addition to a browser surface
• Browser boot — the first-paint sequence
• Import maps — current state and target state for cross-package module sharing
• Cache and invalidation — how (and how little) caching happens today

Two roles, one package

A package's webapp declaration in matrix.json says: this package has a browser app. That declaration creates two effects when the package is mounted:

1. The runtime mounts a MatrixHttpAssetEndpointActor at <appName>.http, pointing at the package's dist/browser/ directory.
2. The runtime advertises the webapp record (appName, routePrefix, shells) via system.runtimes, so the gateway's _loadRoutes can find it.

Both effects come from the same runtime. There is no separate webapp deployer.

Path during dev vs. prod

Mode	Asset source	URL
Production (matrix up @open-matrix/chat)	chat.http asset endpoint reads <package-install-path>/dist/browser/	http://127.0.0.1:3100/apps/chat/
Local dev (matrix run --serve with Vite)	Vite dev server origin (http://127.0.0.1:5173)	http://127.0.0.1:3100/apps/chat/ (same — gateway proxies to dev origin)

The gateway URL is the same in both modes. What changes is the asset source backing it.

Source: Implementation in projects/matrix-3/packages/system-gateway-http/src/. Architecture overview at projects/matrix-3/packages/docs/content/architecture/http-gateway-asset-resolution.md.