hivecast host

Status: target state, partially implemented. There is no hivecast host namespace in the current wrapper. The host-lifecycle verbs are bare today: hivecast install, hivecast start, hivecast stop, hivecast doctor, hivecast seed. This page documents both: what works now, and what a future hivecast host <verb> grouping would consolidate.

Present state — bare verbs

These commands exist today and are the actual way to bring up and manage a local Host:

`hivecast install`

hivecast install [--no-start] [--root <root>] [--http-port <port|0|auto>]

Idempotent first-time setup of a local Host. Lays out <host-home>/, drops the bundled NATS binary, generates host.json, seeds the system + global package store, registers the default runtime targets (system, host-control, gateway, web, edge, director, chat, inference-settings, flowpad, smithers — see hivecast.mjs:28-39), and (unless --no-start) kicks off hivecast start afterwards.

--no-start — install only, do not start runtimes.
--root <root> — override the default authority root.
--http-port <port|0|auto> — pin the gateway HTTP port; 0 or auto lets the OS allocate.

Source: installHostProduct is invoked from hivecast.mjs:1738.

`hivecast start`

hivecast start [--root <root>] [--http-port <port|0|auto>]

Starts the host-service supervisor against an already-installed <host-home>. Brings up the NATS sibling process if it isn't already running, then supervises every runtime whose record has startup: "auto".

Source: startHostProduct is invoked from hivecast.mjs:1743.

`hivecast stop`

hivecast stop

Tears down the host-service supervisor and the NATS sibling. Kills both via pidfile lookup. After commit 4f733013 (P1.30), stop correctly tears down the NATS sibling — earlier versions leaked it.

Source: stopHostProduct is invoked from hivecast.mjs:1765.

`hivecast doctor`

hivecast doctor [--cloud <url>] [--repair] [--json]

Audits the local Host home for known failure modes. With --repair, attempts to self-heal what it can. With --json, emits machine-readable output suitable for monitoring scrapes.

Source: runHostDoctor is invoked from hivecast.mjs:1753.

`hivecast seed`

hivecast seed

Re-seeds the bundled package store under <host-home>/.matrix/packages/ from the wrapper's bundled dist/node_modules/, scans existing runtime records, and reports their health honestly:

json

{
  "ok": true,
  "home": "/home/.../host-home",
  "seeded": true,
  "runtimeRecords": {
    "healthy": 9,
    "corrupt": [
      { "runtimeId": "RUNTIME-HOST-...-HOST-CONTROL", "path": "...", "kind": "empty", "size": 0 }
    ]
  }
}

runtimeRecords.corrupt[] lists records with kind empty, parse-error, or not-object. A subsequent hivecast start self-heals empty records by re-seeding from desired state. This honest reporting was added after the 22-hour zero-byte-runtime.json crash loop (see commit d270d625).

Source: runSeedCommand at hivecast.mjs:494-504; scanRuntimeRecordsHealth at hivecast.mjs:511-554.

Target state — grouped `hivecast host <verb>`

A future revision could group these commands under a host namespace:

hivecast host install [...]
hivecast host start [...]
hivecast host stop
hivecast host doctor [...]
hivecast host seed
hivecast host status

That mirrors the Docker pattern (docker container ...) and keeps the top-level command surface narrow. No code in the current tree implements this grouping. The bare verbs are unambiguous as long as the help text stays accurate.

hivecast host ​

Present state — bare verbs ​

hivecast install ​

hivecast start ​

hivecast stop ​

hivecast doctor ​

hivecast seed ​

Target state — grouped hivecast host <verb> ​

See also ​