Install from registry

The most common install path: resolve a package name against the configured npm-compatible HTTP registry and write the resulting tarball into the package store.

Synopsis

mx install <packageName>[@<version>]
mx install <packageName> --registry <url>
mx install <packageName> --packages-dir <path>
mx install <packageName> --credentials-file <path>
mx install <packageName> --force
mx install <packageName> --json

What happens, step by step

1. mx install parses <packageName>[@<version>] via parsePackageSpecifier (install.ts:66-91).
2. The registry URL is resolved in this order:
   • --registry <url> if passed
   • mx config get registry
   • The default https://registry.hivecast.ai/api/packages/open-matrix/npm/
3. Credentials are read by readRegistryCredential(cwd, { registry, credentialsPath }) (packages/mx-cli/src/utils/auth-store.ts).
4. prepareNpmRegistryTarball (npm-registry-client.ts:37-88) creates a temp dir, writes a temporary .npmrc carrying the token, and shells out to:

   npm pack <packageName>@<version> \
     --pack-destination <tempDir> \
     --registry <url> \
     --userconfig <tempDir>/.npmrc

5. The downloaded .tgz is extracted under another temp dir.
6. installFromDirectory copies the extracted package into <MATRIX_HOME>/packages/global/node_modules/<packageName>/.
7. Install lifecycle hooks run (runInstallLifecycle).
8. Temp dirs are cleaned up; the result is returned (or printed as Installed <name>@<version> -> <targetDir>).

Example

mx install @open-matrix/chat --packages-dir /tmp/matrix-home/packages/global
# Installed @open-matrix/chat@0.2.9 -> /tmp/matrix-home/packages/global/node_modules/@open-matrix/chat

mx install @open-matrix/chat@0.2.5 --force --packages-dir /tmp/matrix-home/packages/global
# Installed @open-matrix/chat@0.2.5 -> ...

Where credentials come from

The credential record is keyed by registry URL. mx login writes it:

mx login --registry https://registry.hivecast.ai/api/packages/open-matrix/npm/ \
         --username my-user \
         --token <opaque token>

Stored at <MATRIX_HOME>/credentials/registry.json by default. Pass --credentials-file <path> to override.

For public packages (typical), the registry returns the tarball without auth. The token is still attached if present; the registry ignores it for read endpoints.

Per-Host install vs per-user install

# Default: install into the current user's MATRIX_HOME
mx install @open-matrix/chat

# Specific Host home (e.g. when supervising a /tmp/matrix-home Host)
mx install @open-matrix/chat --packages-dir /tmp/matrix-home/packages/global

--packages-dir overrides where the package is written. Default is <MATRIX_HOME>/packages per packages/mx-cli/src/utils/package-store.ts:DEFAULT_GLOBAL_PACKAGES_ROOT. The actual install location is <packages-dir>/node_modules/<name>/.

For HiveCast's bundled-package install path, see packages/hivecast/bin/hivecast.mjs:205-216:seedBundledHostPackages. That path copies bundled tarballs straight into the package store without going through the registry — it's the equivalent of an "offline install" for the platform's default packages.

Errors

Error	Cause
MX_REGISTRY_FETCH_FAILED: failed to fetch <spec> from <url>	npm pack couldn't resolve or download the package
Package already installed: <name>	--force not passed; the package already exists
MX_AUTH_REQUIRED:	Auth required for this registry; run mx login
MX_PACKAGE_IDENTITY_MISMATCH:	The downloaded tarball's matrix.json:name doesn't match the request
MX_REGISTRY_INVALID:	Both --registry and --registry-dir passed

See also

• Installing → index
• Installing → Install from local folder
• Installing → Dependency resolution
• Installing → Package store
• Publishing → npm-compatible publication

Source: projects/matrix-3/packages/mx-cli/src/commands/install.ts:599-629 is the registry branch; packages/mx-cli/src/utils/npm-registry-client.ts:37-88 does the actual npm pack call.