Deployless lifecycle

The full lifecycle (Author → Build → Test → Publish → Install → Run → Operate) is not always required. While iterating locally, you can skip Publish and Install and run directly from your source checkout. This page describes that "deployless" inner loop and when to use it.

When deployless is appropriate

• You are developing the package and want fast feedback.
• You need to debug an actor against a real bus without round-tripping through the registry.
• You want to verify a matrix.service.json factory before publishing a release.
• The package depends on workspace-internal @open-matrix/* packages and you want to pick up sibling changes immediately.

It is not appropriate when:

• You need to verify the published artifact is correct (use mx publish --dry-run and mx install for that).
• You're running a Host that is shared across users (CLAUDE.md forbids ad hoc copies into a Host home).
• You want to test the install lifecycle hooks (install.validate, install.migrate, install.seed, install.verify).

The deployless inner loop

# 1. Author or change source
$EDITOR src/MyActor.ts

# 2. Build only what changed
pnpm build:affected

# 3. Run the package straight from the checkout
matrix run . --env dev

matrix run . is the deployless entry point. Source: projects/matrix-3/packages/mx-cli/src/commands/run.ts:233-248.

What it does, in runPackageCommand:

1. Detects whether matrix.service.json exists.
2. Detects whether matrix.json:webapp exists.
3. If matrix.service.json is present and --serve is not requested, loads the standalone bootstrap factory and mounts the package's actors against the environment from .matrix/<env>.environment.json.
4. If --serve is set, additionally starts a same-origin webapp server and mounts the asset endpoint.
5. Holds the runtime open until SIGINT/SIGTERM.

Three deployless modes

# Headless service factory (chat, system, host-control, ...)
matrix run . --env dev

# Web app + service factory in one process
matrix run . --env dev --serve

# Web app only — no service factory (director, flowpad, ...)
matrix run . --env dev --serve

mx up (packages/mx-cli/src/index.ts:965-1012) is the same code path; the only difference is that mx up is documented as the "through Host Service" alias. For a single-package deployless loop the two are equivalent.

Install-from-folder is also deployless-friendly

mx install <local-folder> (see Installing → Install from local folder) copies the package directly into a target Host's store without going through the registry. It does run the install lifecycle hooks. This is the appropriate middle ground when you want to test against a real Host, but the published artifact has not changed.

What the deployless loop deliberately skips

Stage	Skipped?	Reason
Test	No — run separately if needed	Tests are independent of matrix run
Pack	Yes	No tarball produced
Publish	Yes	Nothing pushed to a registry
Install (registry)	Yes	No copy into the Host store
Install hooks	Yes	validate, migrate, seed, verify are not run by mx run

The implication: a package that works under matrix run . may still fail at mx install time if its install hooks have bugs. Run mx install <local-folder> against a scratch home before publishing to surface those.

See also

• Local Development → Run in place
• Local Development → Folder-backed source
• Local Development → Refresh without copying
• Installing → Install from local folder

Source: projects/matrix-3/packages/mx-cli/src/commands/run.ts implements both mx run and the mx up alias body. CLAUDE.md Rule 10 documents the deployless dev loop as the recommended way to verify behavior before broad proofs.