HiveCast Product

Appearance

Install a package ​

A package becomes runnable on a local Host once it is in one of the Host's package stores or referenced by absolute path. This page walks through the three ways to put a package somewhere hivecast up can find it.

Concept — what is a package store ​

Every Host home has two stores under <MATRIX_HOME>/packages/:

StoreLocationPurpose
system/node_modules/Host-internalThe base system actor set (system, host-service, etc). Should NOT be modified by users
global/node_modules/User-facingWhere matrix install and hivecast install (bundled set) put packages

Both are populated automatically by seedBundledHostPackages (hivecast.mjs:205-216) during hivecast install. After install, the Host already has the bundled set: system, @open-matrix/host-control, @open-matrix/system-gateway-http, @open-matrix/system-auth, @open-matrix/matrix-web, @open-matrix/matrix-edge, @open-matrix/director, @open-matrix/chat, @open-matrix/flowpad, @open-matrix/smithers, @open-matrix/inference-settings.

If the package you want is in the bundled set, you don't need to install anything else. Skip to Run a package.

Option A — Already bundled ​

Verify the package is in the global store:

bash
ls /tmp/matrix-home/packages/global/node_modules/@open-matrix/
# chat  director  flowpad  host-control  inference-settings  matrix-edge  matrix-web  smithers  system-auth  system-gateway-http

If yours is on that list, run Run a package directly with the package name.

Option B — From an npm-compatible registry ​

For packages NOT in the bundled set, use the matrix CLI to install from a configured registry:

bash
matrix install @example/my-package --home /tmp/matrix-home

This:

  1. Resolves @example/my-package against the configured Gitea-backed npm-compatible registry (or npm proper, per registry config).
  2. Downloads the tarball.
  3. Extracts into <MATRIX_HOME>/packages/global/node_modules/@example/my-package/.
  4. Installs declared dependencies.

Note — registry config: the matrix CLI reads <MATRIX_HOME>/registry.json (if present) for registry URL + auth. The default is the bundled HiveCast public registry once that is brought up; until it is, matrix install against an external @example/... package requires the package to be available on npm or a registry you've configured.

After install, <MATRIX_HOME>/packages/global/node_modules/@example/my-package/matrix.json should exist.

Option C — From a folder (developer path) ​

If you have package source on disk (typical during development), you don't need to "install" it at all. hivecast up accepts an absolute path:

bash
hivecast up /home/me/packages/my-package --home /tmp/matrix-home

The Host references the source directly — no copy. This is the dev loop.

The same path works through matrix run:

bash
matrix run /home/me/packages/my-package --home /tmp/matrix-home

To make a folder package permanently available under a name, link it into the global store:

bash
ln -s /home/me/packages/my-package /tmp/matrix-home/packages/global/node_modules/@me/my-package

After that, hivecast up @me/my-package works.

Option D — From the source checkout (operators) ​

If you're working from the matrix-work-harness source checkout, hivecast operator refresh-host-package builds and installs one source package into a Host store, optionally restarting it:

bash
hivecast operator refresh-host-package --home /tmp/matrix-home @open-matrix/director

(See hivecast.mjs:73-77 for the operator command surface.) This is for release/deploy operators; normal users use the registry path.

What's in a package directory ​

Every package, regardless of source, has the same shape:

<package-name>/
├── package.json     # npm manifest
├── matrix.json      # mounts, accepts/emits, entrypoints
├── dist/            # built output
└── src/ (optional)  # source, only if shipped

hivecast up reads matrix.json to learn:

  • the default mount(s) to claim
  • the runtime entrypoint
  • declared environment dependencies
  • any UI/component surfaces

See the separate docs-package-lifecycle package for the full matrix.json schema.

Verify the install ​

bash
ls -la /tmp/matrix-home/packages/global/node_modules/@example/my-package/
cat /tmp/matrix-home/packages/global/node_modules/@example/my-package/matrix.json

The presence of matrix.json confirms the package is shaped correctly. If matrix.json is missing, the install brought down something else (an npm-only package, a misnamed tarball).

See also ​

Source: projects/matrix-3/packages/hivecast/bin/hivecast.mjs lines 205-233 (seedBundledHostPackages, listBundledPackageNames); projects/matrix-3/packages/host-service/src/host-paths.ts lines 50-62 (globalPackagesDir, systemPackagesDir); projects/matrix-3/packages/mx-cli/src/cli.ts (matrix install/run implementation).