Artifact registry

The artifact registry is the binary store. Its job is to hand back a tarball when given a package name and version. It owns no metadata search, no live mount state, and no runtime concepts.

Two deployment modes

The same protocol surface (npm-compatible HTTP) is served by two different backends depending on where the Host is running.

Cloud product (HiveCast)

The cloud product runs a Gitea instance behind registry.hivecast.ai. Caddy terminates TLS and proxies to the local Gitea container:

caddyfile

# projects/deploy-cloud/Caddyfile.bare:92-95
registry.hivecast.ai {
  reverse_proxy localhost:3000
}

The npm-compatible URL pattern is:

https://registry.hivecast.ai/api/packages/<scope>/npm/<package>/-/<package>-<version>.tgz

For example:

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

This URL is what npm install @open-matrix/chat resolves to when the consumer has configured the scope:

ini

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

Local install

A local Host (hivecast install --home /tmp/matrix-home) does not need a running Gitea. The hivecast wrapper bundles every default package into its own dist/node_modules/ and copies them into the Host's package store on install:

// projects/matrix-3/packages/hivecast/bin/hivecast.mjs:205-216
function seedBundledHostPackages(matrixHome) {
  const systemNodeModules = join(matrixHome, 'packages', 'system', 'node_modules');
  const globalNodeModules = join(matrixHome, 'packages', 'global', 'node_modules');
  for (const packageName of listBundledPackageNames()) {
    copyBundledPackageToStore(packageName, systemNodeModules);
    copyBundledPackageToStore(packageName, globalNodeModules);
  }
}

Result: <host-home>/packages/system/node_modules/@open-matrix/... is the local artifact store. There is no HTTP endpoint to query; consumption is filesystem-direct.

What lives in an artifact

A Matrix artifact is a normal npm tarball. It contains:

package.json (npm metadata: name, version, dependencies, scripts)
matrix.json (Matrix manifest: components, mounts, webapp, capabilities)
dist/ (built JS, sourcemaps, browser bundles)
README.md, LICENSE

The artifact registry stores all bytes. It does not parse or interpret matrix.json. That is the package catalog's job.

What the artifact registry does NOT do

Capability	Lives in	Not here
Search by description, tag, capability	`system.packages` (package catalog)	yes
List currently-mounted actors	`system.registry` (live actor registry)	yes
Resolve `@open-matrix/chat@^0.2` to a specific version	install resolver (npm semver)	yes
Validate package signatures	(target state) signing pipeline	yes
Hand back package bytes	artifact registry	NO — this is its only job

Authentication

The cloud Gitea instance is admin-credentialed at deploy time:

bash

# projects/deploy-cloud/setup-aws.sh:250-252
GITEA_ADMIN_USER=hivecast-admin
GITEA_ADMIN_PASSWORD=changeme
GITEA_ADMIN_EMAIL=admin@$DOMAIN

Caution: changeme is the literal default in setup-aws.sh and .env.example today. Production deploys must override GITEA_ADMIN_PASSWORD before publishing. See Authentication for current state and rotation rules.

Anonymous read is permitted for public scopes. Publishing requires a Gitea token bound to a user with push access to the open-matrix org.

Artifact registry ​

Two deployment modes ​

Cloud product (HiveCast) ​

Local install ​

What lives in an artifact ​

What the artifact registry does NOT do ​

Authentication ​

See also ​