HiveCast Product

Appearance

hivecast up / down / logs ​

The docker-style verbs of HiveCast: bring a Package up as a supervised Runtime, take it down, watch its logs.

DockerHiveCast
docker run <image>hivecast up <package>
docker stop <container>hivecast down <runtime>
docker logs <container>journalctl -u <unit> (a unified hivecast logs is target state — see below)

hivecast up and hivecast down are real and delegated to the host-service CLI. hivecast logs is not implemented as a top-level subcommand today. This page covers both and describes how to read logs in the meantime.

hivecast up ​

hivecast up <package-or-path>
hivecast up <package-or-path> --id <runtime-id> --mount <actor-mount>
hivecast up <package-or-path> --startup auto --restart always

Starts a package as a supervised runtime on the local Host. The first form auto-allocates a runtime id and uses the package's declared default mount. The second form pins them. The third also persists supervisor policy: startup: auto means restart when the Host starts; restart: always means restart on crash.

<package-or-path> may be:

  • A workspace package name resolvable from <host-home>/.matrix/packages/global/node_modules/, e.g. @open-matrix/director
  • An absolute filesystem path to a package directory containing a valid matrix.json

Source: hivecast.mjs:442-445 (help text) and hivecast.mjs:425 (delegation list, which routes up to the host-service CLI). The actual implementation lives in projects/matrix-3/packages/host-service/src/cli.ts.

Useful flags (delegated to host-service) ​

These pass through unchanged from hivecast up to the host-service CLI:

  • --id <runtime-id> — pin the runtime id (otherwise allocated as RUNTIME-HOST-<scope>-<key>)
  • --mount <actor-mount> — pin the actor mount (otherwise read from matrix.json)
  • --startup auto|manual — supervisor policy
  • --restart always|on-failure|no — restart policy
  • --serve — for webapps, enable static serving on an auto-allocated port
  • --port <n> — pin the serve port
  • --env <name> — environment name (default dev)
  • --env-file <path> — explicit environment file

Examples ​

Bring up Director:

bash
hivecast up @open-matrix/director --serve --startup auto --restart always

Bring up a folder-backed package by absolute path:

bash
hivecast up /home/ubuntu/matrix-work-harness/projects/matrix-3/packages/foo --id FOO-1

hivecast down ​

hivecast down <runtime-id|package|mount>

Stops a supervised runtime. The argument can be:

  • A runtime id (RUNTIME-HOST-LOCAL-1F746E58793D-DIRECTOR)
  • A package name (@open-matrix/director) — stops every runtime whose target is that package
  • An actor mount (director.http) — stops the runtime that owns that mount

Source: same dispatch path as up.

hivecast logs — does NOT exist ​

There is no hivecast logs subcommand in the wrapper. Reading runtime logs today requires one of the following:

On systemd-managed Hosts (.deb install) ​

bash
# host-service supervisor logs
journalctl -u hivecast-host.service -f

# nats-server logs
journalctl -u hivecast-nats.service -f

# matrix-host-edge supervisor (if running as a separate unit)
journalctl -u matrix-host-edge.service -f

# user-host services (if any matrix-user-*.service is in use)
journalctl -u matrix-user-<name>.service -f

On any Host home ​

Each runtime writes its own stdout/stderr files:

bash
ls <host-home>/logs/runtimes/
# RUNTIME-HOST-LOCAL-1F746E58793D-DIRECTOR.stdout.log
# RUNTIME-HOST-LOCAL-1F746E58793D-DIRECTOR.stderr.log
# ...

tail -f <host-home>/logs/runtimes/RUNTIME-HOST-LOCAL-1F746E58793D-DIRECTOR.stdout.log

The Host-Service supervisor itself writes to <host-home>/logs/host.stdout.log and <host-home>/logs/host.stderr.log when not running under systemd.

Target state — hivecast logs <runtime> ​

Status: target state. A future hivecast logs <runtime-id|package|mount> will unify these — tail systemd journal if available, fall back to per-runtime file tail, route through host.control to support remote Hosts paired to the same account. The data already exists; the wrapper subcommand is the missing piece. Tracked as a launch-readiness improvement.

See also ​

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