Install from local folder

mx install <directory> copies a local package directory into the Host's package store. mx install <tarball> does the same after extracting. This is what you use to test the install path without publishing a release.

When to use this

• Verifying that the install lifecycle hooks (install.validate, install.migrate, install.seed, install.verify) work end-to-end.
• Producing a Host whose package store mirrors what a registry install would produce, but without the network round-trip.
• Reproducing a bug whose root cause might be the install copy itself rather than the source code.

If you just want to iterate on source, prefer Folder-backed source — matrix run . skips the install copy entirely.

Synopsis

mx install <directory> [--packages-dir <path>] [--force] [--json]
mx install <tarball.tar.gz> [--packages-dir <path>] [--force] [--json]

What happens for a directory source

1. mx install resolves the directory absolutely.
2. maybeBuildLocalTypescriptPackage (packages/mx-cli/src/commands/install.ts:455-530) checks that runtime.entry exists. If it doesn't but src/ does, the installer transpiles src/ into a staging dir using TypeScript compiler API, producing a usable dist/ for the install.
3. installFromDirectory (install.ts:341-408):
   • Reads and validates matrix.json.
   • Computes the target dir (<MATRIX_HOME>/packages/global/node_modules/<name>/).
   • Copies the source into a uniquely named staging dir.
   • Backs up any existing target dir.
   • Atomically renames staging into the target.
   • Runs runtime npm dependencies install (only for tarball installs).
   • Runs the install lifecycle hooks (validate, migrate, seed, verify).
   • Removes the backup on success.

If anything fails, the backup is restored, the staging dir is removed, and the error is rethrown. The package store is never left in a half-installed state.

What happens for a tarball source

1. The tarball is extracted into a fresh temp dir.
2. locateExtractedPackageDir finds the package directory inside the extracted tree.
3. From there, the flow matches the directory-source case.

Note: for tarball installs the npm-dependency installer runs (installRuntimeNpmDependencies). That step pulls in package.json:dependencies and optionalDependencies. For directory-source installs the dependency installer is skipped on the assumption that you're working from a workspace where dependencies are already resolved.

Example

# Install from a workspace package directly
mx install /abs/path/to/projects/matrix-3/packages/<my-pkg> \
  --packages-dir /tmp/matrix-home/packages/global \
  --force

# Install from a tarball produced by mx pack
cd projects/matrix-3/packages/<my-pkg>
mx pack --build-first
mx install ./.mx-pack/<scope>-<name>-<version>.tar.gz \
  --packages-dir /tmp/matrix-home/packages/global \
  --force

On-the-fly transpile

When you point mx install at a directory whose dist/ does not exist (e.g. you forgot to pnpm build), maybeBuildLocalTypescriptPackage runs a one-shot esbuild-free transpile via the TypeScript compiler API to produce a usable dist/ in the staging dir. This is purposely conservative; it does not replace your real build. Use it as a convenience for tiny scaffolds; for real packages, run pnpm build first.

Errors

Error	Cause
Run target not found: <path>	The directory or tarball doesn't exist
Unsupported install source: <path>	Path exists but is neither a directory nor a tarball
Package already installed: <name>	Target exists; pass --force to overwrite
MX_PACKAGE_IDENTITY_MISMATCH:	matrix.json:name and package.json:name disagree
<pkg> install.<phase> failed	A lifecycle hook returned non-zero; output appended to the error

See also

• Installing → index
• Installing → Install from registry
• Installing → Dependency resolution
• Local Development → Folder-backed source
• Local Development → Refresh without copying

Source: projects/matrix-3/packages/mx-cli/src/commands/install.ts:545-590 handles the directory and tarball branches; installFromDirectory (lines 341-408) is the actual copy + hook runner.