Matrix Package Lifecycle

Appearance

Install from Gitea ​

Status: present state — there is no Gitea-specific install path in mx. Gitea-backed registries are installed through the npm-compatible HTTP install path. This page exists to clarify that "Install from Gitea" and "Install from registry" are the same code path, and to document HiveCast's specifics.

Why no separate Gitea path? ​

Gitea exposes its package store as an npm-compatible HTTP registry at /api/packages/<org>/npm/. From the CLI's perspective, that's a URL that responds to npm pack and npm publish. There is nothing Gitea-specific to handle.

Concretely, packages/mx-cli/src/commands/install.ts has only one HTTP-registry branch (the npm-compatible HTTP registry path); it runs the same code regardless of whether the URL points at Verdaccio, npmjs.org, GitHub Packages, or Gitea.

The HiveCast defaults ​

The CLI default registry resolves to a Gitea-backed URL:

https://registry.hivecast.ai/api/packages/open-matrix/npm/

So:

bash
mx install @open-matrix/chat
# Effectively: mx install @open-matrix/chat \
#   --registry https://registry.hivecast.ai/api/packages/open-matrix/npm/

Because Gitea speaks npm, no flag changes are needed. The installed package ends up at <MATRIX_HOME>/packages/global/node_modules/@open-matrix/chat/, indistinguishable from a package installed from any other npm registry.

Two HiveCast scopes ​

URLWhen to use
https://registry.hivecast.ai/api/packages/open-matrix/npm/Public packages (the default)
https://registry.hivecast.ai/api/packages/hivecast-admin/npm/Restricted platform packages (HiveCast itself, bootstrap)

Operator workflows install hivecast itself with:

bash
npm install -g hivecast \
  --registry https://registry.hivecast.ai/api/packages/hivecast-admin/npm/

This is regular npm install -g, not mx install. The hivecast binary is published to that admin scope; once installed it bundles the rest of the packages locally and does not need to fetch them from Gitea again on the same machine.

Authentication for Gitea ​

Gitea issues personal access tokens with packages:read and packages:write scopes. Store them through mx login:

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

mx install will pick up the token automatically. For unauthenticated reads (most public packages), no login is necessary.

Target state — Gitea-aware tooling ​

Status: target state, not implemented.

A future revision could add Gitea-aware affordances:

  • mx login --gitea <gitea-base-url> that walks the Gitea OAuth device-code flow and writes credentials.
  • mx info --gitea that reaches into Gitea's repository API to surface "this package was published from <git-ref>".
  • Provenance discovery via Gitea webhooks instead of separate publish-time registration.

None of this exists today; the CLI treats Gitea as a generic npm registry and the HiveCast operator scripts handle the Gitea-specific operator concerns (packages/hivecast/scripts/verify-operator-machine.js).

See also ​

Source: projects/matrix-3/packages/mx-cli/src/commands/install.ts:599-629 is the only HTTP-registry install branch; it is registry-agnostic.