Gitea-backed publication

Status: present state, partial. HiveCast's production registry runs on Gitea behind the npm protocol — mx publish and mx install treat it as an ordinary npm-compatible HTTP registry. The Gitea-specific bits (admin vs. public scope, token issuance, container provisioning) are operator-side. This page describes the production layout that exists today plus the boundary an independent Gitea registry would need to meet.

What is "Gitea-backed"?

Gitea is a self-hosted Git server that ships an npm-compatible package registry as a built-in feature. HiveCast runs the matrix-gitea Docker container as the canonical production registry; CLI tools (mx, npm) interact with it through the npm HTTP protocol.

To mx publish, this is just an HTTPS URL. To operators, it's a Gitea instance with admin endpoints, scoped tokens, and storage that must be writable.

The production HiveCast registry

The default URL configured in packages/mx-cli/src/utils/config-store.ts:DEFAULT_PACKAGE_REGISTRY:

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

URL anatomy:

Segment	Meaning
registry.hivecast.ai	Public host (DNS-routed to the Gitea container)
/api/packages/	Gitea's package API
open-matrix/	Gitea organization scope
npm/	npm protocol endpoint inside that scope

A second admin registry exists for HiveCast platform packages:

https://registry.hivecast.ai/api/packages/hivecast-admin/npm/

hivecast-admin/ is restricted; open-matrix/ is the public-publishable scope.

Operator-side guard rails

hivecast operator verify-machine (registered in packages/hivecast/bin/hivecast.mjs:62-65) checks the Gitea container's health on the operator host (packages/hivecast/scripts/verify-operator-machine.js):

Check	What it asserts
docker:matrix-gitea	Gitea container is running
docker:matrix-gitea-writable	Gitea storage volume is writable
npm:gitea-publish-token	Operator has a valid token in npm config

These are operator concerns; they don't appear in the package author's mx publish flow.

Publishing to a Gitea registry

From a package author's perspective, publishing to Gitea is the same as publishing to any npm registry:

mx login --hivecast              # acquire credentials (HiveCast device-code or browser flow)
mx login \
  --registry https://registry.hivecast.ai/api/packages/open-matrix/npm/ \
  --username my-user --token <token>
mx publish --registry https://registry.hivecast.ai/api/packages/open-matrix/npm/

Or, if your CLI config already has the registry set as default (mx config set registry <url>):

mx publish

Internally mx publish shells out to npm publish via packNpmPublishTarball and publishNpmTarball in packages/mx-cli/src/utils/npm-registry-client.ts. From the registry's perspective it sees a stock npm publish request; the storage layer is Gitea instead of CouchDB.

Bootstrap publishing

The HiveCast platform itself uses the registry to ship its bundled packages. The wrapper exposes:

hivecast operator publish-bootstrap          # plan or publish the bootstrap package set
hivecast operator publish-hivecast-release   # pack and publish HiveCast itself

These are operator tools (packages/hivecast/scripts/publish-*.js). They drive mx publish against the same Gitea endpoint and verify that the just-published artifact resolves through registry.hivecast.ai.

Setting up your own Gitea registry

If you run an internal Gitea instance and want to use it as a Matrix package registry:

1. Create a Gitea organization, e.g. my-org.
2. Issue a personal access token with packages:write scope.
3. Configure mx:

   mx config set registry https://gitea.my.example.com/api/packages/my-org/npm/
   mx login --registry https://gitea.my.example.com/api/packages/my-org/npm/ \
            --username me --token <token>

4. mx publish — same as for HiveCast.

There is nothing Matrix-specific about Gitea. Any npm-compatible HTTP registry works the same way. See npm-compatible publication for the protocol details.

See also

• Publishing → npm-compatible publication
• Publishing → Package metadata
• Installing → Install from registry
• projects/matrix-3/packages/docs/content/operations/setup-guide.md for HiveCast registry-specific operations

Source: projects/matrix-3/packages/mx-cli/src/utils/config-store.ts for the default URL; packages/hivecast/scripts/verify-operator-machine.js for the Gitea-specific operator checks.