Package manifest

matrix.json is the single authoritative manifest for a Matrix package. The CLI validator at projects/matrix-3/packages/mx-cli/src/utils/manifestValidator.ts defines exactly what is required and what is optional. This page walks every field that validator inspects.

Validate any time

mx validate                        # validates ./matrix.json (or package.json.matrix)
mx validate ./path/to/matrix.json
mx validate --json

Source: packages/mx-cli/src/commands/validate.ts:72-94.

Required fields

These are the fields without which the validator emits an error:

Path	Type	Validator code
name	non-empty string	MXPKG_NAME_INVALID
version	non-empty string	MXPKG_VERSION_INVALID
runtime.language	non-empty string	MXPKG_RUNTIME_INVALID
runtime.entry	non-empty string	MXPKG_RUNTIME_INVALID
permissions.fsPolicy	one of none, matrix-only, project-readonly, project-readwrite, global-readonly	MXPKG_PERMISSIONS_FSPOLICY_INVALID
components	array (may be empty)	MXPKG_COMPONENTS_NOT_ARRAY

The minimum legal matrix.json:

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

Optional top-level fields

Field	Type	Purpose
description	string	Human-readable description
class	string	High-level shape tag, e.g. "hybrid" (chat uses this)
namespace	string	Logical mount namespace, e.g. "system", "chat"
root	object	Single root actor declaration; alternative or supplement to components[]
webapp	object	Web app surface declaration — see App surfaces
http	object	HTTP routes the gateway should attach to this runtime
consumes	array	Service contracts the package depends on
exports	array	Logical mounts this package promises to provide
config	object	Config schema/defaults/providers — see Config contract
install	object	Install lifecycle hooks (validate, migrate, seed, verify)

Component declarations (components[])

Each entry of components[] describes one actor class. Validator rules (manifestValidator.ts:158-244):

Field	Required	Type	Validator code
type	yes	non-empty string	MXPKG_COMPONENT_TYPE_INVALID
export	no	non-empty string when present	MXPKG_COMPONENT_EXPORT_INVALID
mount	no	non-empty string when present	MXPKG_COMPONENT_MOUNT_INVALID
autoStart	no	boolean	MXPKG_COMPONENT_AUTOSTART_INVALID
props	no	object	MXPKG_COMPONENT_PROPS_INVALID
fsPolicy	no	same enum as top-level permissions.fsPolicy	MXPKG_COMPONENT_FSPOLICY_INVALID

Real example, from packages/system/matrix.json:

{
  "type": "RuntimeManagerActor",
  "export": "RuntimeManagerActor",
  "mount": "system.runtimes",
  "autoStart": true,
  "surface": "headless",
  "description": "Physical runtime inventory and lifecycle control",
  "accepts": [
    "runtimes.ps", "runtimes.list", "runtimes.status",
    "runtimes.instances", "runtimes.reconcile",
    "runtimes.start", "runtimes.stop", "runtimes.reload"
  ]
}

surface, description, accepts, and emits on a component are not enforced by the CLI validator today but are read by introspection tools and by the discovery extractor (packages/mx-cli/src/utils/discovery-extractor.ts).

Install lifecycle hooks

matrix.json:install.<phase>.script declares scripts that mx install runs in order. Each phase entry must be an object with a script field:

{
  "install": {
    "validate": { "script": "scripts/validate-install.js", "description": "Check prerequisites" },
    "migrate":  { "script": "scripts/migrate.js" },
    "seed":     { "script": "scripts/seed.js" },
    "verify":   { "script": "scripts/verify.js" }
  }
}

Phases run in this order: validate, migrate, seed, verify. See Installing → Dependency resolution.

permissions object

{
  "permissions": {
    "fsPolicy": "global-readonly",
    "hostApi": "same-origin",
    "network": true,
    "subprocess": false,
    "env": true
  }
}

Field	Validator
fsPolicy (required)	none, matrix-only, project-readonly, project-readwrite, global-readonly
hostApi (optional)	none, same-origin
network	boolean
subprocess	boolean
env	boolean

The current validator only enforces shape. Runtime enforcement is target state — see Capability declarations.

Identity coupling: matrix.json vs package.json

packages/mx-cli/src/utils/package-store.ts enforces that the name in matrix.json agrees with package.json.name, modulo scope alias between @matrix/ and @open-matrix/. The version is read from package.json, not matrix.json, by mx publish and mx install (readVersionFromPackageDir).

Caution: Keep matrix.json:version and package.json:version in sync. Today only package.json drives publishing, but the manifest validator still requires a non-empty matrix.json:version. Mismatches mislead readers and confuse audit tools.

See also

• Reference → Manifest schema
• Authoring → Runtime entrypoints
• Authoring → Actor declarations
• Authoring → App surfaces
• Authoring → Config contract
• Authoring → Capability declarations

Source: projects/matrix-3/packages/mx-cli/src/utils/manifestValidator.ts is the live validator. mx validate reports diagnostics from this module verbatim.