Login / pair a device

This step is optional. A local Host works without ever pairing to a HiveCast account. Pair when you want this Device to appear in an account's Devices list, participate in a Space, or be reachable from a browser session signed into a HiveCast platform.

If you're just trying it out locally, skip to Install a package.

Two flavors of the same ceremony

Form	Best for	Behaviour
hivecast login --device --cloud <url>	Workstation users with a browser	Opens a browser to the cloud's OAuth surface, waits for approval
hivecast connect <url>	Headless / scripted setups	Non-interactive; takes the cloud URL as a positional argument

Both produce the same on-disk result: a <MATRIX_HOME>/credentials/hivecast-link.json and a heartbeat to the cloud's /_auth/host-link/heartbeat endpoint.

Browser-pair from a workstation

hivecast login --device \
  --cloud https://hivecast.ai \
  --route-key alt.stories.ghost-stories.funny \
  --home /tmp/matrix-home

What happens:

1. hivecast.mjs:1595-1635 (runHiveCastLinkCommand) forwards the args to mx-cli login with --hivecast and --wait.
2. mx-cli opens a browser to https://hivecast.ai/<route-key>/devices/pair?....
3. You sign into the HiveCast account in the browser.
4. The cloud creates an enrollment, you approve it, the cloud redeems it.
5. The local CLI persists the link record into <MATRIX_HOME>/credentials/hivecast-link.json and exits zero.

The --route-key flag pre-claims a public Space-path. Per the v1 alias rules, this is the same as --space-path (target state); use --route-key today.

Headless connect

hivecast connect https://hivecast.ai \
  --route-key alt.stories.ghost-stories.funny \
  --name "richard-laptop" \
  --home /tmp/matrix-home

The wrapper normalizes the positional URL to --cloud (normalizeConnectArgs in hivecast.mjs:1637-1662), then forwards to mx-cli login. The --device flag is added implicitly. The connect form fits scripted device-fleet enrollment.

Note: --name sets hostName, the mutable human label. The stable management key (deviceSlug) is allocated by system-auth from hostName once, then stays put. See Glossary → Host name.

Setup-code form

If the Device is offline / behind a firewall, generate a setup code from the HiveCast Devices page and paste it:

hivecast login --setup-code <code-from-devices-page> \
  --cloud https://hivecast.ai \
  --home /tmp/matrix-home

This avoids the browser-pair round trip. Handy for IoT-style enrollments.

Verify the link

hivecast whoami --home /tmp/matrix-home

Should print principal / Space / Device metadata. If "not linked," the pairing didn't complete.

hivecast link-status --home /tmp/matrix-home

More detailed: cloud reachability, last successful heartbeat, last error if any.

What's now on disk

After successful pairing, three files in <MATRIX_HOME>/credentials/ cooperate:

File	Created by	Carries
hivecast-install.json	hivecast install	installId (durable per-install)
hivecast-link.json	hivecast login --device	hostId, hostName, deviceSlug, authorityRoot, principal/Space metadata, per-device NATS credentials
host.json	hivecast install	local Host config (independent of cloud link)

See CLI → hivecast login / whoami / logout for what each field means.

Per-device credentials

After pairing, system-auth issues a device-scoped NATS JWT credential to this Device. From WORKSTREAMS/product-launch/HIVECAST-DEVICE-ENROLLMENT-SPEC.md:

device-code and browser-pair exchanges now return device-scoped NATS JWT credentials from system.auth; setup exchange writes those scoped credentials to the local Device credential files when available.

The principal account seed remains server-side. This Device cannot impersonate other Devices on the same account; revocation is per-Device.

Pairing to your own (non-hivecast.ai) cloud

The --cloud flag accepts any HiveCast-shaped endpoint. For self-hosted setups:

hivecast login --device --cloud https://my-hivecast.example.com --route-key richard

For dev — pairing one local Host to a sibling local Host playing the platform role (per CLAUDE.md):

hivecast login --device --cloud http://127.0.0.1:3100 --route-key dev-pair-test

Disconnecting

Command	Effect
hivecast logout	Deletes hivecast-link.json locally. Cloud still considers the Device linked until heartbeat goes stale
hivecast logout --revoke-cloud-link	Revokes the link on the cloud side too
hivecast logout --all	--revoke-cloud-link PLUS clears hivecast-install.json (regenerates installId on next install)

See CLI → hivecast login / whoami / logout.

Troubleshooting

If login hangs or errors:

• Check the cloud is reachable: curl -fsS https://hivecast.ai/healthz
• Check <host-home>/logs/runtimes/RUNTIME-HOST-...-HOST-CONTROL.stderr.log for heartbeat errors
• See Troubleshooting → Device pairing failed

See also

• Cloud Account → Device pairing — full ceremony detail.
• Cloud Account → Security model — what credentials live where.
• CLI → hivecast login / whoami / logout — the wrapper-side reference.

Source: projects/matrix-3/packages/hivecast/bin/hivecast.mjs lines 1595-1635 (runHiveCastLinkCommand) and 1637-1662 (normalizeConnectArgs); WORKSTREAMS/product-launch/HIVECAST-DEVICE-ENROLLMENT-SPEC.md.