Hosted runtimes

Status: most of this is target state. Today, all runtimes execute on the Devices that ran hivecast up. The HiveCast cloud platform (hivecast.ai) does not yet host third-party runtimes on behalf of users. This page documents the model that the architecture supports and that the docs portal TOC anticipates; concrete cloud-execution features are tracked in WORKSTREAMS/product-launch/.

What "hosted" means in this product

HiveCast does not run user runtimes in the cloud. Per WORKSTREAMS/product-launch/HIVECAST-DEVICE-ENROLLMENT-SPEC.md:

Visibility And Director Model: The source of truth for "what is on this device" is headless inventory. Director is not the source of truth. Director is a UI over those platform actors.

The cloud platform plays three roles:

1. Authentication — OAuth, principal/Space management.
2. Discovery — system.devices lists every linked Device, system.registry lists logical mounts that Devices have published.
3. Routing — when a browser session signed into hivecast.ai invokes an actor on a paired Device, the cloud routes the call over the Device's bus (via the Device's leaf-style WebSocket connection back to the cloud's NATS).

Execution stays on Devices.

Why this matters

This shape solves several constraints simultaneously:

• Inference credentials never leave the Device. Per CLAUDE.md Rule 4: "Credentials go through Factotum ONLY. Inference credentials NEVER leave the local machine."
• Compute cost stays with the Device owner. No cloud-side billing for inference; all spend is on your own keys.
• Privacy stays with the Device. A user's chat history lives on their workstation, not on hivecast.ai.
• Offline / air-gapped works. A Device can run without the cloud.

The trade-off: a Device must be reachable for the cloud to route to it. Devices that are powered off, sleeping, or behind a firewall without the leaf connection cannot serve cloud-side requests.

Runtime model on a single Device (concrete, works today)

Per Local Device → Runtime records, each Device's <MATRIX_HOME>/runtimes/<runtime-id>/runtime.json is the authoritative record. A Device runs all its own runtimes, each with its own pid, mounts, and policy. The cloud has no involvement in that supervision.

When the Device is paired, host-control heartbeats inventory (the runtime list) to the cloud. The cloud's system.devices projection updates accordingly.

Cloud-side routing (target state, partial)

When a paired Device sets up its NATS connection to the cloud, it does so as a leafnode-style outbound WebSocket (per CLAUDE.md):

Leaf connection is outbound WebSocket — no open ports needed. User's daemon initiates WSS to hivecast.ai.

That gives the cloud's NATS a route into the Device's bus. A request from a browser session signed into hivecast.ai to an actor mounted on the Device gets routed via that leaf.

Today this works for:

• the system.devices heartbeat path (cloud → Device for inventory updates is target; Device → cloud for heartbeat works)
• some host-control ops

It does not yet uniformly work for arbitrary user-facing actors. Tracked in WORKSTREAMS/product-launch/STATUS.md.

What "hosted runtimes" page WOULD cover (target)

A future iteration of HiveCast might add cloud-side execution for specific opt-in runtimes — e.g. a small worker runtime the cloud spawns for users who pay for it. If that arrives, this page will document:

• which runtimes are eligible
• how to opt a runtime into cloud hosting
• where the data lives (cloud vs Device)
• the billing model
• the authority-root semantics for cloud-hosted runtimes

None of this is in code today. Mentioning it here so the documentation surface matches the TOC.

What you can do today

• See your paired Device's runtime list from hivecast.ai's Devices page (when the cloud is configured to display this — currently a launch readiness item).
• Invoke an actor on your paired Device from a browser signed into hivecast.ai — same authority-root surface as your local browser session.
• Manage your Devices: pair, unpair, rename. (Disconnect device action exists per the spec.)

What you cannot do today

• Run a runtime on hivecast.ai's infrastructure.
• Pay HiveCast to execute inference on your behalf.
• Have the cloud auto-failover when your Device is offline.

Self-hosted "hosted" runtimes

If you self-host the platform Host role on a server with persistent uptime, you can effectively get hosted execution by running the runtimes on THAT Host. From a Device-Linked perspective, that server is just another Device — its runtimes are visible in the principal's Devices list like any other Device's.

This is the supported pattern for "always-on" runtimes today: stand up a server-class Device, pair it, and the runtimes that need to be reachable 24/7 live there.

See also

• Device pairing — the leaf connection's prerequisite.
• Security model — what credentials cloud-side routing uses.
• Overview → Local host vs cloud platform — the core model.
• WORKSTREAMS/product-launch/STATUS.md — what's shipped vs target state.

Source: repo-root CLAUDE.md "Production / leaf connection" notes; WORKSTREAMS/product-launch/HIVECAST-DEVICE-ENROLLMENT-SPEC.md (Visibility And Director Model section).