Run in place

matrix run . runs a package directly from your checkout. No publishing, no installation into a Host home. The runner reads matrix.json, matrix.service.json (if present), .matrix/<env>.environment.json, and starts a runtime in your shell.

Synopsis

matrix run <target> [options]

<target> is either a package directory (preferred) or a single actor file (legacy mode).

Common options (packages/mx-cli/src/index.ts:902-963):

Option	Purpose
--env <name>	Load .matrix/<name>.environment.json
--env-file <path>	Load an explicit environment file
--serve	Start the standalone webapp server (web-app packages only)
--check	Boot once, then shut down and exit
--json	Emit a JSON result
--mount <mount>	Override the standalone mount
--root <root>	Override the standalone root
--config <path>	Override the instance configRef JSON path
--secrets <path>	Load secretRefs from a JSON file for this run
--overrides <json>	Merge JSON over matrix.service.json:bootstrap.overrides
--entry <path>	Override matrix.service.json:entry
--export <name>	Override matrix.service.json:export

Three concrete recipes

Headless service factory

Your package has matrix.service.json and no webapp block.

cd projects/matrix-3/packages/system
pnpm build
matrix run . --env dev

The runner imports runtime.entry, calls createStandaloneSystem, mounts the system actors. The shell stays foregrounded; the runtime holds open until SIGINT/SIGTERM.

Pure web app

Your package has a webapp block but no matrix.service.json. The custom elements are the actors.

cd projects/matrix-3/packages/director
pnpm build
matrix run . --env dev --serve

The runner mounts a MatrixHttpAssetEndpointActor, starts the standalone webapp server on a free port, and prints something like:

[mx run] serving @open-matrix/director at http://127.0.0.1:5173
[mx run] bootstrap: http://127.0.0.1:5173/bootstrap
[mx run] nats-ws: http://127.0.0.1:5173/nats-ws

Open the printed URL in a browser.

Hybrid

Your package has both matrix.service.json AND webapp.

cd projects/matrix-3/packages/chat
pnpm build
matrix run . --env dev --serve

The runner does both: it calls the service factory and starts the webapp server. Same-origin: the browser bootstrap connects to NATS at /nats-ws on the same port the assets are served from.

What the environment file controls

--env dev reads .matrix/dev.environment.json. Required fields:

Field	Notes
name	Must match the env name
runtime.root	Wire root for the bus

Optional but very useful:

Field	Purpose
nats.mode	embedded (start an embedded NATS) or external (connect to a URL)
nats.port, nats.wsPort	When embedded, which ports to bind
nats.url, nats.wsUrl, nats.credentialsRef	When external
runtime.runtimeId	Stable id for system.runtimes
http.port	Port for the standalone webapp server
host.matrixDir	Path to a Host home; runs that share files (e.g. host.json) read from here

A real example, from 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 }
}

Lifecycle while running

The runner reports lifecycle state through the runner control plane:

starting → live → stopping → stopped
                    ↓
                  failed

Ctrl+C (SIGINT) triggers shutdownAll (packages/mx-cli/src/commands/run.ts:426-449): stops the webapp server, shuts down the service factory, deregisters the runtime, and closes the runner runtime handle.

mx up is the same code path

mx up <target> [--env <name>] [--serve] ...

packages/mx-cli/src/index.ts:965-1012 defines up as a thin wrapper that calls the same runCommand. Use mx up when you want the "supervised by Host Service" framing; use mx run when you're in deployless mode. The runner code is identical.

See also

• Overview → Deployless lifecycle
• Local Development → Folder-backed source
• Local Development → Refresh without copying
• Authoring → Runtime entrypoints

Source: projects/matrix-3/packages/mx-cli/src/commands/run.ts implements both mx run and mx up bodies.