hivecast up

hivecast up <package-or-path> starts a runtime that supervises a package. The wrapper passes through to the host-service CLI's up command, which assembles a startSpec and invokes runtime.start against the running Host.

Synopsis

From packages/hivecast/bin/hivecast.mjs:442-444:

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

Full option set (packages/host-service/src/cli.ts:270-362):

Option	Purpose
--home <path>	Host home (default ~/.matrix)
--env <name>	Run environment to load (default host)
--id <id> / --runtime-id <id>	Override the auto-allocated runtime id
--mount <mount>	Override the package's primary mount
--port <port>	Pin the webapp port for --serve runtimes (auto for OS-allocated)
--serve	Start the standalone webapp server
--startup <manual|auto>	Whether the Host should auto-start this runtime on boot
--restart <never|always|on-failure>	Restart policy when the runtime exits
--auto-start-priority <n>	Boot ordering hint (lower starts first)
--timeout <ms>	Time to wait for the runtime to report ready
--control <host-control|supervisor>	Which control facade to invoke (default host-control)
-- <command...>	Pass-through command and args; bypasses the default run command

What it does, in order

1. Resolves the package target via resolvePackageTarget (host-service/src/cli.ts:390-...):
   • If the target is an existing directory path → folder-backed.
   • Otherwise → look up by name in the global package store, then the system store.
2. Reads metadata from the resolved package (readPackageMetadata).
3. Reads the running Host's status (readRunningHostStatus).
4. Allocates a runtimeId if not provided (defaultRuntimeIdForTarget), and derives runtimeMount / controlMount.
5. If a runtime with the same id is already registered as running, reports skipped: already-running and returns.
6. If --serve, allocates a webapp port via resolveServePort.
7. Writes a per-runtime environment file at <host-home>/runtime-env/<runtimeId>.json (writeHostRuntimeEnvironment).
8. Builds the startup command — by default the bundled mx run binary; with --, the caller's pass-through.
9. Builds the startSpec and invokes:
   • runtime.start on host.control (default), or
   • runtime.start on the supervisor (--control supervisor)
10. Prints the result as JSON.

Three concrete recipes

Start a system package by name

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

The Host resolves @open-matrix/system to its installed copy in <host-home>/packages/system/node_modules/@open-matrix/system/, allocates RUNTIME-HOST-SYSTEM, mounts the system actors, and returns the runtime descriptor.

Start a webapp on a known port

hivecast up @open-matrix/director --serve --port 5173 \
  --id RUNTIME-DIRECTOR-DEV --env hivecast \
  --startup auto --restart always \
  --home /tmp/matrix-home

The runtime serves Director on http://127.0.0.1:5173/apps/director/, auto-starts on Host boot, and is restarted forever if it crashes.

Start a folder-backed runtime

hivecast up /abs/path/to/projects/matrix-3/packages/<my-pkg> \
  --env hivecast --home /tmp/matrix-home

The Host imports runtime.entry from the absolute path. Useful during development when iterating on a single package without publishing.

Idempotency

If a runtime with the same runtimeId already exists and is running, up returns { skipped: true, reason: "already-running" } rather than starting a second copy. Override the runtime id explicitly with --id if you want a second runtime of the same package.

Default runtimes

hivecast install lists the runtimes that come up by default (packages/hivecast/bin/hivecast.mjs:28-39):

Target	Runtime key	--serve?	autoStartPriority
system	SYSTEM	no	0
@open-matrix/host-control	HOST-CONTROL	no	2
@open-matrix/system-gateway-http	GATEWAY	no	5
@open-matrix/matrix-web	WEB	yes	10
@open-matrix/matrix-edge	EDGE	yes	15
@open-matrix/director	DIRECTOR	yes	20
@open-matrix/chat	CHAT	yes	25
@open-matrix/inference-settings	INFERENCE-SETTINGS	yes	30
@open-matrix/flowpad	FLOWPAD	yes	35
@open-matrix/smithers	SMITHERS	yes	40

You can issue additional hivecast up calls after install to bring up packages outside this default set.

See also

• Running → hivecast down
• Running → Logs
• Running → Health
• Running → Update
• Deployment Profiles → Runtime instances

Source: projects/matrix-3/packages/host-service/src/cli.ts:145-235 implements the up command; packages/hivecast/bin/hivecast.mjs:420-479 is the wrapper that delegates.