Run a package

A package becomes a supervised runtime when hivecast up claims it. This is one process, registered with the Host, restartable, with on-disk record. This page walks through the common shapes.

The simplest form

hivecast up @open-matrix/director --home /tmp/matrix-home

The Host:

1. Resolves @open-matrix/director against <MATRIX_HOME>/packages/global/node_modules/@open-matrix/director/.
2. Reads its matrix.json to discover entrypoint, default mount, declared environment.
3. Allocates a runtime id (RUNTIME-HOST-LOCAL-<token>-<key>).
4. Spawns the runtime process.
5. Persists <MATRIX_HOME>/runtimes/<runtime-id>/runtime.json with status: "running", the pid, the command line, and metadata.
6. Returns when the runtime is healthy.

If the package's default mount is already claimed by another runtime, the Host rejects the new claim. hivecast doctor will flag duplicate live claims.

Pinning a runtime id and mount

hivecast up @open-matrix/director \
  --runtime-id DIRECTOR-DEV \
  --mount director.http \
  --home /tmp/matrix-home

--runtime-id and --mount override the auto-allocated values. Useful when scripts need stable ids or you want to override a package's default mount.

Adding supervisor policy

hivecast up @open-matrix/director \
  --startup auto \
  --restart always \
  --home /tmp/matrix-home

Flag	Values	Meaning
--startup	auto | manual	If auto, the Host brings this runtime up at start; if manual, you must hivecast up again after a restart
--restart	always | on-failure | never	Restart policy on crash

After hivecast install, every default runtime is registered with --startup auto --restart always (see bootstrapDefaultHostRuntimes in hivecast.mjs:1432-1456). Mirror that for any runtime you want to survive restarts.

Webapps — --serve

For packages that are also webapps, --serve enables static serving from the gateway:

hivecast up @open-matrix/chat \
  --serve \
  --startup auto --restart always \
  --home /tmp/matrix-home

The gateway picks an auto-allocated port. Pin it with --port:

hivecast up @open-matrix/chat --serve --port 5050 --home /tmp/matrix-home

The webapp is then reachable through the gateway at /<routePrefix>/ — typically /apps/chat/. The runtime's runtime.json records the route prefix in metadata.webapp.routePrefix.

Folder-backed packages

Replace the package name with an absolute path:

hivecast up /home/me/packages/my-package \
  --runtime-id MY-PKG-1 \
  --home /tmp/matrix-home

The Host references the source directly — no copy. The runtime's runtime.json records packageDir instead of packageRef.

Setting an environment

Each runtime is associated with an environment name:

hivecast up @open-matrix/director --env hivecast --home /tmp/matrix-home

Default is dev. The .deb install uses hivecast as the environment name. Per-environment files live under <MATRIX_HOME>/runtime-env/<env>/<runtime-id>.env and are sourced by the runtime when it starts.

Verifying

hivecast runtimes --home /tmp/matrix-home

Should list your runtime with status: "running". If not running:

cat /tmp/matrix-home/runtimes/<runtime-id>/runtime.json
tail /tmp/matrix-home/logs/runtimes/<runtime-id>.stderr.log

The runtime record is the authoritative source. The status field will be one of starting, running, stopping, stopped, failed. See Local Device → Runtime records.

If your webapp loaded but the actor mailbox isn't reachable from the browser, see Troubleshooting → NATS connection failed.

Stopping

hivecast down <runtime-id|package|mount> --home /tmp/matrix-home

The argument can be:

• a runtime id (RUNTIME-HOST-LOCAL-XXXX-DIRECTOR)
• a package name (@open-matrix/director — stops every runtime targeting that package)
• an actor mount (director.http — stops the runtime that owns that mount)

down also clears the supervisor policy (startup: auto) for the runtime so it doesn't auto-start next time. To keep the policy and only stop the process, use host-service down directly with --keep-policy (target state — not yet exposed through hivecast).

See also

• Quickstart → Open the dashboard — the final verification step.
• CLI → hivecast up / down — full reference.
• Local Device → Runtime records — what's in runtime.json.
• Troubleshooting → Package failed to start — when hivecast up returns non-zero.

Source: projects/matrix-3/packages/hivecast/bin/hivecast.mjs line 425 (delegation list) and 442-445 (signatures); projects/matrix-3/packages/host-service/src/cli.ts (host-service up implementation).