What is a Matrix package?

A Matrix package is a directory on disk that contains everything the matrix CLI and the Host Service need in order to install, run, and supervise a unit of Matrix code. It is the unit of distribution. The artifact you publish to a registry is a tarball of this directory.

The required files

A package directory MUST contain the two manifests:

File	Purpose	Authoritative validator
`matrix.json`	Identity, runtime entry, declared components, permissions, optional install hooks	`validateManifestForMxCli` in `projects/matrix-3/packages/mx-cli/src/utils/manifestValidator.ts`
`package.json`	npm metadata: `name`, `version`, `dependencies`, `files`	npm

Status: target state — single manifest (P1.41). Today some packages still ship a sidecar matrix.service.json declaring the bootstrap factory. P1.41 absorbs that file: matrix.json becomes the single manifest with explicit runtime / instance / components / service sections, per-component relativeMount mandatory. See P1.41.

The package name in matrix.json must agree with the name in package.json (or differ only by the @matrix/ / @open-matrix/ scope alias). assertMatrixAndPackageJsonAgree enforces this in packages/mx-cli/src/utils/package-store.ts.

A package directory MAY contain:

File or directory	Purpose
`matrix.service.json`	Standalone bootstrap factory contract. Required if the package is started as a service runtime (`mx run .`, `matrix up <pkg>`) without an external bootstrap.
`src/`	TypeScript source. `mx init` scaffolds this directory.
`dist/`	Build output the runtime executes from. Path is declared in `runtime.entry`.
`dist/browser/` (or `dist/`)	Web app build output for `webapp.distDir`.
`.matrix/<env>.environment.json`	Per-environment runtime config consumed by `mx run . --env <env>`.
`tests/`	`mx init` creates this with a sample test file.
`examples/`, `skills/`	`mx init` creates these for documentation/example assets.
`LICENSE`, `README.md`	Standard project files.

A minimal `matrix.json`

This is exactly what mx init writes for a brand-new package (projects/matrix-3/packages/mx-cli/src/commands/init.ts:71-78):

json

{
  "name": "my-package",
  "version": "0.1.0",
  "description": "",
  "runtime": {
    "language": "typescript",
    "entry": "dist/index.js"
  },
  "components": [],
  "permissions": {
    "fsPolicy": "none"
  }
}

The validator requires name, version, runtime.language, runtime.entry, and permissions.fsPolicy. components must be an array (it may be empty). See Package manifest for the full field inventory and Manifest schema for the exact validation rules.

Three package shapes you will see in this repo

The shape that fits a package is determined by what extra fields are present in matrix.json and whether matrix.service.json exists.

Library / pure framework

A small matrix.json (often empty components) and a dist/index.js runtime entry. Other packages import it. It is not started directly.

Headless service package

matrix.json declares components and a runtime.entry. The package also ships a matrix.service.json with kind: "factory" and an export such as createStandaloneSystem. Example: projects/matrix-3/packages/system/matrix.json declares twelve actor components and matrix.service.json exports createStandaloneSystem which mounts them at runtime startup.

Web app package (or hybrid)

matrix.json adds a top-level webapp object. Example: projects/matrix-3/packages/director/matrix.json:

json

{
  "name": "@open-matrix/director",
  "version": "0.1.28",
  "runtime": { "language": "typescript", "entry": "dist/index.html" },
  "webapp": {
    "distDir": "dist",
    "entry": "index.html",
    "appName": "director",
    "displayName": "Director",
    "shells": ["platform", "edge"]
  },
  "components": [],
  "permissions": { "fsPolicy": "none" }
}

Hybrids combine both: chat's manifest has components (headless actor proxies that run inside the runtime) and a webapp block (the browser UI). It also sets runtime.browserEntry and runtime.bootstrapEntry for browser-side execution.

What is not a package

The retired daemon (projects/matrix-3/packages/daemon/) is not the package execution path. CLAUDE.md Rule 1 forbids new product behavior there. Also, a Matrix actor source file by itself is not a package — mx run ./MyActor.ts --mount foo exists but is the "legacy actor-file mode" called out in packages/mx-cli/src/commands/run.ts:74 and is not the path package authors should use for new work.

What is a Matrix package? ​

The required files ​

A minimal matrix.json ​

Three package shapes you will see in this repo ​

Library / pure framework ​

Headless service package ​

Web app package (or hybrid) ​

What is not a package ​

See also ​