hivecast down

hivecast down <target> stops a runtime that the Host is supervising. The wrapper delegates to the host-service CLI's down command, which invokes runtime.stop on host.control.

Synopsis

From packages/hivecast/bin/hivecast.mjs:445:

hivecast down <runtime-id|package|mount>

Common options (packages/host-service/src/cli.ts:237-252):

Option	Purpose
`--home <path>`	Host home (default `~/.matrix`)
`--id <id>` / `--runtime-id <id>`	Use a specific runtime id (alternative to positional)
`--timeout <ms>`	Time to wait for graceful shutdown (default 15000ms)

Resolving the target

The argument can be one of:

A runtime id: RUNTIME-HOST-CHAT.
A package name: @open-matrix/chat.
A logical mount: chat (the runtime's primary mount).

resolveRuntimeStopTarget (in packages/host-service/src/cli.ts) walks the live runtime registry looking for a unique match. Ambiguous matches throw an error naming the candidates; you have to be more specific (e.g. pass the runtime id explicitly with --id).

What it does

packages/host-service/src/cli.ts:237-252:

if (command === 'down') {
  const target = options.runtimeId ?? positionals[0];
  const runtimeId = options.runtimeId ? target : resolveRuntimeStopTarget(target, options.home);
  const status = readRunningHostStatus(options.home);
  printJson(await invokeHostControlFromStatus(
    status,
    'runtime.stop',
    { runtimeId },
    options.timeoutMs ?? 15_000,
  ));
}

The runtime.stop op asks host.control to:

Send the runtime's control mount a shutdown request.
Wait up to --timeout ms for the runtime to exit cleanly.
If it doesn't, send SIGTERM. If it still doesn't, SIGKILL.
Deregister the runtime from system.runtimes.

Logs and runtime records are not removed. They sit under <host-home>/logs/runtimes/<runtimeId>.stdout.log and <host-home>/runtimes/<runtimeId>.json so an operator can investigate after the fact.

Examples

bash

# By runtime id (most explicit)
hivecast down RUNTIME-HOST-CHAT --home /tmp/matrix-home

# By package name (resolved to its runtime)
hivecast down @open-matrix/chat --home /tmp/matrix-home

# By mount
hivecast down chat --home /tmp/matrix-home

All three end up at the same runtime.stop invocation; only the resolution step differs.

Idempotency and re-entry

hivecast down against a runtime that is already stopped returns a result indicating no work was done. Calling it twice is safe.

If --timeout elapses before the runtime exits, the supervisor escalates to SIGTERM/SIGKILL. The CLI returns whatever host.control reports. Inspect logs to understand why the runtime didn't shut down cleanly.

Bringing the runtime back

bash

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

If you set --restart always or --startup auto on the original up call, restarting the Host (hivecast stop/hivecast start) will bring it back automatically because the runtime record on disk is still there.

What `down` does not do

Concern	Status
Stop the Host itself	No — use `hivecast stop`
Remove the runtime record	No — record persists for reuse
Uninstall the package	No — use `mx uninstall`
Free webapp ports	The OS reclaims the port when the process exits
Notify other runtimes	Bus-wide events emit when `system.runtimes` updates

hivecast down ​

Synopsis ​

Resolving the target ​

What it does ​

Examples ​

Idempotency and re-entry ​

Bringing the runtime back ​

What down does not do ​

See also ​