npm-compatible packages

The Matrix artifact registry speaks the npm registry protocol. That is the entire point of using Gitea — every existing npm/pnpm tool already knows how to talk to it. There is no Matrix-proprietary install protocol on top.

URL surface

The npm protocol used by Matrix consumers is:

Operation	URL	Method
Fetch package metadata (versions list, latest tag)	`/api/packages/<owner>/npm/<package>`	GET
Fetch a tarball	`/api/packages/<owner>/npm/<package>/-/<package>-<version>.tgz`	GET
Publish a tarball	`/api/packages/<owner>/npm/<package>`	PUT
Deprecate a version	(Gitea admin UI / API)	—

For the cloud product, <owner> is the Gitea user/org that owns the registry — typically hivecast-admin (the admin user provisioned by setup-aws.sh):

https://registry.hivecast.ai/api/packages/hivecast-admin/npm/@open-matrix/chat
https://registry.hivecast.ai/api/packages/hivecast-admin/npm/@open-matrix/chat/-/chat-0.2.3.tgz

Consumer configuration

Matrix uses scoped resolution so only @open-matrix/* packages route to the private registry; everything else continues to resolve via npmjs.com:

ini

# .npmrc (typical consumer)
@open-matrix:registry=https://registry.hivecast.ai/api/packages/hivecast-admin/npm/
//registry.hivecast.ai/:_authToken=${GITEA_TOKEN}

The deploy pipeline uses the same convention internally:

bash

# projects/deploy-cloud/deploy.sh:145
docker run --rm -v $REMOTE_DIR:/app/.matrix -w /app/.matrix node:22-slim sh -c \
  'echo "@open-matrix:registry=$GITEA_REGISTRY" > .npmrc && npm install --production --silent'

$GITEA_REGISTRY defaults to https://registry.hivecast.ai/api/packages/hivecast-admin/npm/ (projects/deploy-cloud/deploy.sh:43).

Tarball layout

A Matrix package tarball is a normal npm tarball. Inside, after extraction:

package/
├── package.json          # npm metadata
├── matrix.json           # Matrix manifest (components, mounts, webapp)
├── README.md
├── LICENSE
└── dist/                 # built artifacts
    ├── index.js
    ├── ...
    └── browser/          # browser bundle (for webapp packages)

The artifact registry treats this tarball as opaque bytes. Matrix-specific files (matrix.json, dist/browser/) are not validated by the registry — that's the responsibility of the publish pipeline and consumers.

What is NOT in the registry surface

The Matrix artifact registry does not extend the npm protocol. It does not serve:

matrix.json independently of the tarball.
A discovery search endpoint. Search lives in system.packages (the package catalog), reading a separate discovery-index.json.
A live actor catalog. That lives in system.registry.
Per-package homepage / docs URLs (those are in package.json.repository and package.json.homepage like any normal npm package).

Tag semantics

Matrix uses standard npm dist-tags:

Tag	Meaning in Matrix
`latest`	Default version pulled by `npm install <pkg>` with no version specified.
`next`	Pre-release candidates. (Target state — currently unused.)
`beta`, `alpha`	Per-channel pre-releases. (Target state — unused.)

Status: Channel tagging beyond latest is target state for Matrix. The publish pipeline currently writes only latest. See Channels for the planned multi-channel flow.

Compatibility envelope

Matrix's npm compatibility is intentionally strict. Any change to the artifact registry that breaks npm install is a breaking product change. The consumer side runs unmodified npm/pnpm, so:

URL layout cannot change without bumping the registry's external surface.
Tarball format is npm-canonical.
Header conventions (Authorization: Bearer <token>, Content-Type: application/json) are npm-canonical.

npm-compatible packages ​

URL surface ​

Consumer configuration ​

Tarball layout ​

What is NOT in the registry surface ​

Tag semantics ​

Compatibility envelope ​

See also ​