Start a local host

After Install the CLI, bring up a local Host. One command is enough; this page walks through what it does and how to verify success.

Step 1 — hivecast install

hivecast install --home /tmp/matrix-home

Flags worth knowing:

Flag	Default	Notes
--home <path>	~/.matrix (or MATRIX_HOME env var, or /var/lib/hivecast on .deb)	Host home directory
--no-start	start by default	Lay the home out but don't bring up the supervisor
--root <root>	COM.OPEN-MATRIX.LOCAL.AUTHORITY	Authority root for this Host's bus traffic
--http-port <port|0|auto>	3100	Pin gateway HTTP port; 0 or auto = OS-allocate

What it does, end-to-end (from installHostProduct in hivecast.mjs:1511-1539):

1. seedHostProductHome — write host.json, make runtimes/, runtime-env/, logs/runtimes/, packages/{global,system}/node_modules/, bin/. Copy bundled NATS binary.
2. assertHostProductInstallable — verify host-service/cli.js, the NATS binary, and the matrix-edge package are all present in the bundle.
3. (unless --no-start) startHostProduct — start the NATS sibling process; spawn the host-service supervisor; wait for host.status.json to land; bootstrap default runtimes.
4. Print one JSON object summarizing what was set up.

A successful install ends with stdout like:

{
  "ok": true,
  "installed": true,
  "started": true,
  "home": "/tmp/matrix-home",
  "host": {
    "mode": "local-owner",
    "service": "host-service"
  },
  "nats": {
    "mode": "external",
    "binary": "/tmp/matrix-home/bin/nats-server"
  },
  "edge": {
    "installed": true,
    "url": "http://127.0.0.1:3100/apps/edge/"
  },
  "start": { "ok": true, "status": { ... }, "nats": { ... }, "bootstrap": [ ... ] }
}

If you used the .deb install, the postinst already ran the equivalent — you don't need to run hivecast install again. Skip to step 2.

Step 2 — Verify the Host is up

Three commands. Each catches a different class of failure.

hivecast status

hivecast status --home /tmp/matrix-home

Reads <host-home>/host.status.json plus a live process check. Returns JSON describing the Host's HTTP origin, transport, supervisor mount, and uptime. If the Host crashed silently, status will say so.

hivecast runtimes

hivecast runtimes --home /tmp/matrix-home

Lists all supervised runtimes. After a fresh install you should see the ten default runtimes from hostDefaultRuntimeTargets (hivecast.mjs:28-39):

• RUNTIME-HOST-LOCAL-<token>-SYSTEM
• RUNTIME-HOST-LOCAL-<token>-HOST-CONTROL
• RUNTIME-HOST-LOCAL-<token>-GATEWAY
• RUNTIME-HOST-LOCAL-<token>-WEB
• RUNTIME-HOST-LOCAL-<token>-EDGE
• RUNTIME-HOST-LOCAL-<token>-DIRECTOR
• RUNTIME-HOST-LOCAL-<token>-CHAT
• RUNTIME-HOST-LOCAL-<token>-INFERENCE-SETTINGS
• RUNTIME-HOST-LOCAL-<token>-FLOWPAD
• RUNTIME-HOST-LOCAL-<token>-SMITHERS

…each with status: "running". The <token> is the first 12 hex chars of sha256(host-home-path) (see defaultRuntimeScope in hivecast.mjs:1297-1302).

curl /healthz

curl -fsS http://127.0.0.1:3100/healthz

A 2xx response confirms the gateway is serving. If the port is in use, the gateway runtime will have failed and hivecast runtimes will show it as failed. Pass --http-port <other> to install and try again.

hivecast doctor

hivecast doctor --home /tmp/matrix-home

Audits the Host home for ten or so common failure modes (see CLI → exit codes and diagnostics). Add --json for machine-readable output, --repair to auto-fix what it can.

Step 3 — Open the bundled webapps

Default ports, all on the same gateway origin (127.0.0.1:3100):

URL	Webapp
http://127.0.0.1:3100/apps/web/	matrix-web (account/platform shell)
http://127.0.0.1:3100/apps/edge/	matrix-edge (local-Device shell)
http://127.0.0.1:3100/apps/director/	Director (the dashboard)
http://127.0.0.1:3100/apps/chat/	Chat
http://127.0.0.1:3100/apps/flowpad/	FlowPad
http://127.0.0.1:3100/apps/inference-settings/	Inference Settings
http://127.0.0.1:3100/apps/smithers/	Smithers

If a page loads but the actor mailbox is unreachable from the browser, it's almost certainly a NATS WebSocket problem — see Troubleshooting → NATS connection failed.

What's now on disk

/tmp/matrix-home/
├── host.json                                # config (auth.mode=local-client, http.port=3100, ...)
├── host.status.json                         # live status (status=running, pid=...)
├── host.pid                                 # supervisor pid
├── runtimes/RUNTIME-HOST-LOCAL-XXXX-SYSTEM/runtime.json
├── runtimes/RUNTIME-HOST-LOCAL-XXXX-GATEWAY/runtime.json
├── ... (one dir per default runtime)
├── nats/host-default/
│   ├── nats-server.conf
│   ├── nats-server.pid
│   └── jetstream/
├── packages/global/node_modules/@open-matrix/director/...
├── packages/system/node_modules/system/...
├── credentials/hivecast-install.json        # installId
├── logs/host.stdout.log, host.stderr.log
├── logs/runtimes/<runtime-id>.{stdout,stderr}.log
├── logs/nats.stdout.log, nats.stderr.log
└── bin/nats-server[.exe]

See Reference → Filesystem layout for the full schema.

Stopping the Host

hivecast stop --home /tmp/matrix-home

Tears down the host-service supervisor AND the sibling NATS process (the latter via pidfile lookup). Both must stop for the next hivecast start to bind cleanly. After commit 4f733013 (P1.30), hivecast stop correctly tears down NATS — earlier versions leaked it.

See also

• Quickstart → Login / pair a device — the next page (optional).
• CLI → hivecast host (install / start / stop / doctor / seed) — full reference.
• Local Device → Start / stop / restart — operational lifecycle.

Source: projects/matrix-3/packages/hivecast/bin/hivecast.mjs lines 1511-1539 (installHostProduct) and 1464-1509 (startHostProduct); default runtimes list at lines 28-39.