Packages

A Matrix package is the smallest deployable unit. It carries a matrix.json, optionally a webapp surface, optionally a list of headless actors, optionally a configuration contract, and a runtime entrypoint that the runner imports. This section is the field guide.

Pages in this section

Page	What you'll learn
Package manifest	The full matrix.json shape — every documented field, defaults, and which combinations are valid today.
Package config contract	The config.{schema,defaults,envPrefix,providers} block and how resolveConfiguredPackageConfig reads it.
Package metadata	Discovery metadata: namespace, runtime classes, execution-class compatibility.
Runtime entrypoints	runtime.entry, runtime.browserEntry, runtime.bootstrapEntry, what each is loaded by.
App surfaces	webapp block: appName, displayName, shells, routePrefix, distDir.

What a package looks like in 30 seconds

projects/matrix-3/packages/director/
├── matrix.json                # discovery + runtime contract
├── package.json               # npm/workspace metadata, scripts, deps
├── README.md
├── src/                       # TypeScript sources
├── tests/                     # node:test specs
├── vite.config.ts             # browser bundle config
└── dist/                      # built artifacts (gitignored)

matrix.json is the file the framework reads. package.json is what pnpm reads. They overlap on name and version and otherwise describe different things — matrix.json describes the runtime contract, package.json describes the npm/workspace contract.

Three classes of package, by content

Class	Has webapp	Has components	Example
Webapp-only	yes	no	director, flowpad, inference-settings
Headless-only	no	yes	system-auth, host-control, system-gateway-http
Hybrid	yes	yes	chat

The runner reads the manifest and decides what to do. A webapp-only package gets a --serve HTTP listener; a headless-only package mounts its components and stays silent on HTTP; a hybrid does both.

Quick "is my package valid?" checklist

• matrix.json exists at package root.
• name matches package.json's name.
• version is set.
• One of webapp, components, or runtime.entry is present (otherwise the runner has nothing to do).
• If webapp is present, webapp.distDir, webapp.entry, webapp.appName, webapp.shells are all set.
• If components[] is non-empty, every entry has type, mount, surface.
• permissions declares at least fsPolicy.

hivecast doctor audits a running install for several of these conditions. The SDK itself does not validate matrix.json at import time — invalid manifests fail at matrix run time.

See also

• SDK vs runtime host — how the runner consumes matrix.json.
• Component packaging — UI-side of a package.

Source: projects/matrix-3/packages/{chat,director,flowpad,inference-settings,smithers}/matrix.json (real shipping examples), projects/matrix-3/packages/core/src/runtime/PackageConfigResolver.ts.