Package vs app

In Matrix, "app" specifically means a web-app surface served by a runtime through the Host's HTTP gateway. A package becomes an app when its matrix.json includes a top-level webapp block. Apps are URL endpoints; packages are distribution units.

The webapp block opts a package into being an app

matrix.json:webapp.* (validated by packages/mx-cli/src/utils/webapp-manifest.ts) declares:

Field	Purpose
appName	Slug used in the gateway route prefix /apps/<appName>/
displayName	Human-readable title shown in shells and nav
icon	Emoji/glyph used in nav
navOrder	Sort order in shell navigation
description	One-line description
distDir	Directory containing built browser assets, relative to package root
entry	Entry HTML file inside distDir, usually index.html
shells	Which shells host this app (platform, edge)
base	Base path mode (relative is the supported value today)

director's manifest:

"webapp": {
  "distDir": "dist",
  "entry": "index.html",
  "appName": "director",
  "displayName": "Director",
  "icon": "🧭",
  "navOrder": 20,
  "description": "Matrix actor hierarchy explorer",
  "shells": ["platform", "edge"]
}

When the runtime starts with --serve, the runner mounts a MatrixHttpAssetEndpointActor for the package and registers the route /apps/<appName>/ with the gateway. See packages/mx-cli/src/commands/run.ts:526-559.

Three relationships you need to keep straight

Relationship	True?	Why
1 package = 1 app	No	A package may have zero apps (system, host-control) or many components but exactly one webapp block. The repo today caps each package at one app surface.
1 app = 1 package	Yes	An appName like director belongs to exactly one package. The route prefix /apps/director/ resolves to that one package's assets.
1 Host = 1 app of each name	Yes	The gateway routes /apps/<appName>/ based on the unique appName slug. Two packages claiming the same appName is an error.

Apps cohabit the same Host

A single Host can serve multiple apps because each runtime registers its assetMount against a distinct appName. The default hivecast install brings up six web apps (see packages/hivecast/bin/hivecast.mjs:28-39):

appName	Package	Role
web	@open-matrix/matrix-web	Account/platform shell, OAuth surface
edge	@open-matrix/matrix-edge	Local-Device shell
director	@open-matrix/director	Actor hierarchy explorer
chat	@open-matrix/chat	Conversation workspace
inference-settings	@open-matrix/inference-settings	LLM provider config
flowpad	@open-matrix/flowpad	Flow-based composition surface
smithers	@open-matrix/smithers	Operator dashboard

Browse to http://127.0.0.1:3100/apps/<appName>/ after hivecast start.

Apps are not the only surface

A package can contribute to the running system without being an app:

• Headless service: system, system-gateway-http, host-control declare actors but no webapp.
• Library: pure utility (no components, no webapp).
• Web component shipped as part of a hybrid: chat has actor components AND a webapp block; the actor proxies serve the chat web app's bus traffic, while the webapp block carries the browser assets.

See also

• What is a Matrix package?
• Authoring → App surfaces
• Running → hivecast up
• Deployment Profiles → Gateway routes

Source: projects/matrix-3/packages/mx-cli/src/utils/webapp-manifest.ts defines the webapp block; packages/mx-cli/src/commands/run.ts:526-559 shows how --serve mounts the asset endpoint and gateway route.