Desired state

The Host's desired state is the union of:

1. The Host process itself (described by host.json).
2. The set of runtime records under <host-home>/runtimes/.
3. The per-runtime environment files under <host-home>/runtime-env/.

Anything in this set with startup: "auto" is part of the steady- state expectation. Host Service reconciles this set at startup and keeps it in mind as it supervises runtimes.

How the desired state gets written

Two paths today populate <host-home>/runtimes/:

Path	Trigger
hivecast install	Seeds the default runtime records for each entry in hostDefaultRuntimeTargets (packages/hivecast/bin/hivecast.mjs:28-39)
hivecast up <pkg> (the user-driven path)	Adds a runtime record when an explicit up is invoked

Both write JSON records of shape IHostRuntimeStartSpec (see packages/host-service/src/cli.ts:196-229 for the construction site).

What startup: "auto" means

A record with startup: "auto" is started by the Host on its own during hivecast start. A record with startup: "manual" exists on disk but is not auto-started; an explicit hivecast up invokes it.

hivecast install defaults: every default runtime gets startup: "auto" (and restart: "always") so a fresh install boots a working Host without further commands. Custom hivecast up calls default to startup: "manual", restart: "never"; pass --startup auto --restart always to make a custom runtime persistent across Host restarts.

Reconciliation at boot

When hivecast start runs:

1. Host Service reads host.json.
2. Walks <host-home>/runtimes/ and reads each record.
3. Skips records that fail to parse (the bootstrap parse-and-skip commit 895a0688 documented in projects/matrix-3/packages/docs-hivecast/content/cli/exit-codes-and-diagnostics.md).
4. Sorts by autoStartPriority (lower first).
5. For each startup: "auto" record, spawns the runtime per its command/args.
6. Watches each runtime's exit; respects restart policy.

Reading the desired state

hivecast runtimes --home /tmp/matrix-home
ls /tmp/matrix-home/runtimes/

hivecast runtimes returns the live view of system.runtimes, which combines the records on disk with their currently-known state. The on-disk files are the source of truth across restarts; the live view is the source of truth for "is it serving right now?"

Modifying the desired state

Goal	Recipe
Add a runtime to the auto-start set	hivecast up <pkg> --startup auto --restart always --home <home>
Remove a runtime from the auto-start set	hivecast down <runtimeId> (current state) plus delete its record file (persistent removal)
Change a runtime's port	hivecast down <runtimeId> → hivecast up <pkg> --port <new-port> ...
Change a runtime's mount	hivecast down <runtimeId> → hivecast up <pkg> --mount <new-mount> ...

Don't hand-edit runtime records. CLAUDE.md "ONE DEPLOY PATH" applies. The hivecast up/hivecast down cycle is the supported mutation surface. Hand-editing has historically corrupted records (zero-byte runtime.json was a 22-hour outage).

Target state — a unified profile

Status: target state, not implemented.

A future revision could collapse host.json + runtimes/*.json + runtime-env/*.json into one deployment-profile.json that declares the entire desired state. The reconciler would diff that profile against the live state and apply the delta. Today's two-step (records + env files) is the live shape.

WORKSTREAMS/runtime-environment-multi-instance/ is the active workstream for the unified profile.

See also

• Deployment Profiles → Runtime instances
• Deployment Profiles → Verification
• Running → hivecast up
• Running → hivecast down

Source: projects/matrix-3/packages/host-service/src/host-state-store.ts persists records; packages/host-service/src/cli.ts:196-229 writes them on up; packages/hivecast/bin/hivecast.mjs:28-39 declares the default runtime targets.