Package refs

A package ref is the string that identifies a package for mx install, mx run, matrix up, and similar commands. Three forms are accepted today.

1. Scoped name (most common)

@open-matrix/chat
@open-matrix/director
@open-matrix/system-inference-openai

A scoped npm name. Resolves through the configured registry for the scope:

ini

# .npmrc
@open-matrix:registry=https://registry.hivecast.ai/api/packages/hivecast-admin/npm/

Without explicit version, resolves to the latest dist-tag.

2. Name plus version range

@open-matrix/chat@^0.2
@open-matrix/chat@0.2.3
@open-matrix/chat@>=0.2.0 <0.3.0
@open-matrix/chat@beta

Standard npm version specifiers — semver ranges and dist-tags both accepted. Resolution is npm's resolution; Matrix does not customize it.

3. Folder / path ref

matrix run /work/my-chat-plugin
matrix run ./packages/director
matrix up /home/ubuntu/checkout-of-package

A filesystem path is treated as a "package source" pointing directly at a package directory containing package.json and matrix.json. The package is not installed through the registry; it is mounted from the path.

This is the path used during local development. The HTTP gateway resolves packageSource.path + webapp.distDir to an absolute dist directory at runtime (see architecture/http-gateway-asset-resolution).

What is NOT a package ref

Form	Why not
Tarball URL (`https://.../foo.tgz`)	Not currently supported by Matrix tooling. npm/pnpm support this; Matrix's CLI doesn't expose it.
Git URL (`git+ssh://...`)	Not currently supported. npm supports it; Matrix's CLI doesn't expose it.
Bare name without scope	Implicit scope inference is not supported. `@open-matrix/chat`, not `chat`.

Wire-format mount paths vs. package refs

This is a frequent confusion. They are unrelated:

Concept	Example
Package ref (install-time identity)	`@open-matrix/chat`
Mount path (runtime logical name)	`chat`, `system.devices`, `director.assistant`
Wire subject (NATS subject after authority root)	`COM.NIMBLETEC.RICHARD-SANTOMAURO.chat.$inbox`

A package can mount actors at any number of mount paths. The package ref is the install-time identity; the mount path is the runtime locator. They are declared in matrix.json.components[*].mount, not derived from each other.

Authority root vs. package ref

Authority root is also unrelated:

Concept	Example	Where it comes from
Package ref	`@open-matrix/chat`	npm
Authority root	`COM.NIMBLETEC.RICHARD-SANTOMAURO`	derived from user identity (email) or Space

Two different users can install the same package; their actors run under different authority roots. The package ref is identical; the wire prefix is not.

Package refs ​

1. Scoped name (most common) ​

2. Name plus version range ​

3. Folder / path ref ​

What is NOT a package ref ​

Wire-format mount paths vs. package refs ​

Authority root vs. package ref ​

See also ​