HiveCast Platform

Appearance

Deployment profiles ​

Status: target state. Deployment profiles do not exist as first-class records today. The data model is per-runtime records under <host-home>/runtimes/*.json. This page documents the intended profile contract and the relationship to today's primitives.

Today: per-runtime records ​

Today, "what runs on this Host" is the union of files under <host-home>/runtimes/. Each file is a JSON record:

json
{
  "runtimeId": "WEB",
  "package": "@open-matrix/matrix-web",
  "mount": "matrix.web",
  "env": "hivecast",
  "serve": true,
  "port": 5001,
  "startup": "auto",
  "restart": "always"
}

hivecast install writes the default set (system, host-control, system-gateway-http, matrix-web, matrix-edge, director, chat, inference-settings, flowpad, smithers). host.control runtimes.declare creates additional records. The Host Service supervisor reconciles records against running processes.

This works for one Host. It does not scale to "deploy v2 of director to every Device that has director" or "stage a rollout of the new gateway."

Target: declarative profiles ​

Per WORKSTREAMS/docker-npm-parity/ and the runtime-environment-multi-instance workstream, a deployment profile would be:

yaml
# profiles/production.yaml
profile: production
authorityRoot: SPACE.SPC_XXX
runtimes:
  - id: WEB
    package: '@open-matrix/matrix-web'
    version: 0.4.2
    serve: true
    port: 5001
    startup: auto
    restart: always
  - id: EDGE
    package: '@open-matrix/matrix-edge'
    version: 0.4.2
    serve: true
    port: 5002
    startup: auto
    restart: always
  - id: DIRECTOR
    package: '@open-matrix/director'
    version: 0.5.0
    startup: auto
    restart: always

A profile is declarative. The reconciler computes a diff between the profile and the running state, then drives the diff to zero through host.control ops. Editing the profile triggers a controlled rollout.

Profile scope ​

A profile would target one of:

  • One Device — by hostLinkId or deviceSlug.
  • A fleet of Devices — selected by tag, routeKey, or org.
  • All paired Devices for a principal.
  • All Devices in a Space.

Today there is no scope concept beyond "this <host-home>." Multi-Device profiles require the orchestrator to reach Devices via NATS, which means the per-Device host.control mount must accept declarative profile.apply ops. Those ops are target state.

Profile vs runtime record ​

A profile is the desired state. A runtime record is the current declared state on one Host. The reconciler bridges them:

  • Profile says runtime WEB should be at version 0.4.2 → reconciler updates the record and triggers host.control runtimes.reload.
  • Profile removes runtime LEGACY-X → reconciler stops and removes it.
  • Profile adds runtime NEW-Y → reconciler runtimes.declare + runtimes.start.

The reconciler must be idempotent and convergent. Today the supervisor is convergent for the records it sees but has no concept of "desired profile" — it converges to whatever records exist locally.

Versioning a profile ​

Profiles would be versioned. A profile change is a new revision; the rollout machinery (see Rollouts) advances Devices through revisions. Rollback (see Rollback) reverts to a prior revision.

This requires a profile store with revision history. None exists today.

Profile authority ​

A profile applies under an authorityRoot. Operators authoring a profile must have rights on that authority root (own the Space). Cross-Space profile application would require federation primitives that don't exist.

Loose ends ​

  • No formal spec yet beyond WORKSTREAMS/docker-npm-parity/.
  • No reconciler implementation.
  • No host.control profile.apply op.
  • No profile store or revision schema.

See also ​

Source: WORKSTREAMS/docker-npm-parity/ and WORKSTREAMS/runtime-environment-multi-instance/. Today's runtime-record primitives are at projects/matrix-3/packages/host-control/src/index.ts.