Config contract schema

This page lists every field in the two config-related schemas:

1. The matrix.json:config block (per-package; conventional, not enforced by the CLI validator).
2. .matrix/<env>.environment.json (per environment; enforced by loadPackageEnvironment in packages/mx-cli/src/utils/package-environment.ts).

matrix.json:config block

Conventional shape used by chat, system, etc.:

interface IMatrixConfigBlock {
  readonly schema?: string;       // path to JSON Schema file
  readonly defaults?: string;     // path to JSON defaults file
  readonly envPrefix?: string;    // convention used by the env provider
  readonly providers?: readonly IMatrixConfigProvider[];
}

type IMatrixConfigProvider =
  | { kind: "env"; prefix: string; }
  | { kind: "file"; env: string; optional?: boolean; }
  | { kind: "service"; service: string; namespace: string; env?: string; optional?: boolean; };

Provider kinds in use today:

kind	Required fields	Meaning
env	prefix	Read environment variables that start with prefix
file	env	Read a file path from the named env var
service	service, namespace	Look up config under service/namespace via an actor

IMatrixPackageEnvironment

packages/mx-cli/src/utils/package-environment.ts:6-35:

interface IMatrixPackageEnvironment {
  readonly name: string;
  readonly nats?: {
    readonly mode?: string;
    readonly port?: number;
    readonly wsPort?: number;
    readonly url?: string;
    readonly wsUrl?: string;
    readonly credentialsRef?: string;
    readonly dataDir?: string;
    readonly pidFile?: string;
    readonly binaryPath?: string;
  };
  readonly runtime: {
    readonly root: string;
    readonly runtimeId?: string;
    readonly runtimeMount?: string;
    readonly controlMount?: string;
  };
  readonly package?: { readonly publicRoot?: string; };
  readonly http?: { readonly enabled?: boolean; readonly port?: number; };
  readonly host?: { readonly matrixDir?: string; };
}

Required:

Path	Type	Notes
name	string	Must match the env name passed to mx run --env <name>
runtime.root	string	The wire root for the bus

Optional:

Path	Type	Notes
nats.mode	"embedded" | "external"	When embedded, runs an embedded NATS sibling
nats.port, nats.wsPort	number	When embedded
nats.url, nats.wsUrl	string	When external
nats.credentialsRef	string	URL/path to NATS credentials
nats.dataDir, nats.pidFile, nats.binaryPath	string	Embedded-NATS sibling config
runtime.runtimeId	string	Stable id
runtime.runtimeMount, runtime.controlMount	string	Mount overrides
package.publicRoot	string	Public namespace root for the package
http.enabled	boolean	Whether to start the standalone HTTP server
http.port	number	Port for the standalone HTTP server
host.matrixDir	string	Path to a Host home (for runtimes that share files)

A canonical example

projects/matrix-3/packages/director/.matrix/dev.environment.json:

{
  "name": "dev",
  "nats": {
    "mode": "embedded", "port": 4330, "wsPort": 4331,
    "dataDir": ".matrix/state/dev/nats",
    "pidFile": ".matrix/state/dev/nats-server.pid"
  },
  "runtime": {
    "root": "COM.OPEN-MATRIX.LOCAL.DIRECTOR",
    "runtimeId": "director-dev"
  },
  "package": { "publicRoot": "director" },
  "http": { "enabled": true, "port": 4332 }
}

Validation behavior

loadPackageEnvironment throws if:

• The env name is empty
• The file at .matrix/<env>.environment.json doesn't exist
• The file isn't valid JSON / isn't a JSON object
• parsed.name is missing
• parsed.runtime.root is missing

Other fields are read defensively; absent fields default to undefined.

What does NOT belong here

• Credentials. Use secretRefs in matrix.service.json.
• Cross-package roots. Each runtime has one wire root; share it via Host host.json:transport.root instead of duplicating in env files.
• Hand-tuned per-Host overrides. The Host-side equivalent is runtime-env/<runtimeId>.json, written by hivecast up.

See also

• Authoring → Config contract
• Local Development → Config explain
• Deployment Profiles → Config
• Reference → Deployment profile schema

Source: projects/matrix-3/packages/mx-cli/src/utils/package-environment.ts defines and enforces the per-environment file shape; matrix.json:config is read by individual package factories.