Local host vs cloud platform

Every HiveCast install is fundamentally local. Pairing to hivecast.ai (or any HiveCast-shaped cloud endpoint) is an additive ceremony — it adds an authenticated account context on top of the local Host. It does not move execution off the Device.

The two modes side by side

	Local-only Host	Cloud-paired Host
`hivecast install` runs	Yes	Yes
`hivecast start` runs	Yes	Yes
Bundled webapps available	Yes	Yes
`auth.mode` in `host.json`	`local-client`	`local-client` (still — the local Host never moves to public-session just because it's paired)
`<MATRIX_HOME>/credentials/hivecast-link.json`	absent	present
Identity advertised to runtimes	local install id (`installId`)	install id + cloud `hostId` + Space metadata
Authority root for the bus	derived locally (e.g. `COM.OPEN-MATRIX.LOCAL.AUTHORITY`)	derived from the principal (e.g. `COM.NIMBLETEC.RICHARD-SANTOMAURO`)
Cloud heartbeat	none	`host.control` heartbeats to `<cloud>/_auth/host-link/heartbeat`
Visibility from `hivecast.ai`	none	this Device appears in the account's Devices list
Inference credentials	local Factotum only	still local — credentials never leave the Device
Browser shell	usable on `127.0.0.1:3100`	usable on `127.0.0.1:3100` AND linked to the cloud account

The key insight: pairing changes who knows about the Device, not where the Device runs. Per CLAUDE.md:

Inference credentials NEVER leave the local machine.
Anthropic/Codex OAuth → Local HiveCast install / Factotum (Localhost redirect, credentials stay local)

When local-only is enough

Use a local-only install if you want:

a workstation/dev environment that doesn't need a cloud account
a homelab Host that should not depend on hivecast.ai reachability
an air-gapped or restricted-network deployment
to evaluate HiveCast before signing up for an account

You get the full bundled webapp experience on http://127.0.0.1:3100/apps/{web,edge,director,chat,flowpad,smithers}/. system.devices will list this Device under the local authority root; nothing reaches the public internet unless you specifically configure inference providers that talk to OpenAI/Anthropic/etc.

When you want to pair

Pair if you want:

to see this Device alongside other Devices owned by the same account
to navigate to this Device from a browser session signed into hivecast.ai
to participate in a Space (a shared public address)
to receive over-the-air package updates from the account's package set
to use the cloud-side audit, billing, or shared-actor features (target state — not all are shipped)

Run:

bash

hivecast login --device --cloud https://hivecast.ai --route-key <space-path>

…or the non-interactive form:

bash

hivecast connect https://hivecast.ai --route-key <space-path>

The link is recorded into <MATRIX_HOME>/credentials/hivecast-link.json. The Host then begins sending heartbeats to the cloud and adopts the principal's authority root for new operations. The local install id (installId) is preserved across pairing — that's the durable per-install identifier.

See Cloud Account → Device pairing for the full ceremony.

What "the cloud platform" actually is

A HiveCast cloud platform is itself a Host. There is no separate "cloud product" with a separate codebase. From CLAUDE.md:

For self-contained dev — one container or one workstation — matrix-web plays the platform/HiveCast role (account-facing shell, dashboard, OAuth surface) and matrix-edge plays the personal-Device role (local Host UI, runtime inventory). Both run as independent --serve runtimes inside the same Host Service, sharing the worker's local NATS, the same authority root, and the same system.devices. No production hivecast.ai traffic.
This is the same code path that production HiveCast runs in its own Docker setup.

The production hivecast.ai is therefore a Host that has been brought up:

with auth.mode: 'public-session' (so unauthenticated browser visitors can hit the auth gateway)
with real OAuth credentials for Google / GitHub / Apple / etc
with DNS pointed at it
with a TLS terminator in front of it
accepting Device Link heartbeats on /_auth/host-link/heartbeat

Pairing your local Host to that Host is the "cloud" experience.

Self-hosting the cloud role

You can run a personal HiveCast instance and pair Devices to it instead of the public hivecast.ai:

bash

# On a server with TLS termination
hivecast install --home /var/lib/hivecast --http-port 3100
# Configure auth.mode: 'public-session' and OAuth credentials separately

# On a Device
hivecast login --device --cloud https://my-personal-hivecast.example.com

This is supported by design (the --cloud flag accepts any HiveCast-shaped endpoint). It is the same code path as hivecast.ai. See Cloud Account → Security model.

Local host vs cloud platform ​

The two modes side by side ​

When local-only is enough ​

When you want to pair ​

What "the cloud platform" actually is ​

Self-hosting the cloud role ​

See also ​

Local host vs cloud platform

The two modes side by side

When local-only is enough

When you want to pair

What "the cloud platform" actually is

Self-hosting the cloud role

See also