Disconnect

hivecast logout is the disconnect command. It comes in three variants and the difference matters: one cleans up locally, one revokes cloud-side, and one does both plus also rotates the install identity.

Three variants

hivecast logout [--local-only] [--revoke-cloud-link] [--all]

Flag	Cloud-side effect	Local-side effect	When to use
(none) / --local-only	none	remove hivecast-link.json, hivecast-nats.json, hivecast-host-link-token, credentials.json; reset host.json transport to local-owner	"I'm done using this Device against this account, but I'll re-pair shortly"
--revoke-cloud-link	call auth.hostLink.revoke first	then run the same local cleanup as --local-only	"this Device is sold/decommissioned/lost — revoke its credential at the cloud"
--all	call auth.hostLink.revoke first	run the same local cleanup AND delete hivecast-install.json (so the next install regenerates installId)	"wipe this install completely — next pair will look like a brand-new Device"

Default vs --local-only

These are the same command. The --local-only flag is the explicit form, useful in scripts where the intent should be visible. The cloud row remains active until heartbeats time out cloud-side; explicit --revoke-cloud-link is preferred when the Device is no longer trusted.

What --revoke-cloud-link does

The Host calls auth.hostLink.revoke({ id: <hostLinkId>, principalId, hostId }) against the cloud. The cloud:

• looks up the active Host Link
• sets its status to revoked
• sets revokedAt
• saves

Future heartbeats from the same bearer token return HTTP 403 because verifyHeartbeatToken() returns null for revoked links. The system.devices view will show the Device as revoked once the Host Link is loaded into the next devices.list projection.

After cloud revoke succeeds, the local cleanup runs the same way as --local-only. If cloud revoke fails (network down, cloud unreachable), the local cleanup still runs. The Device cannot reach the cloud now anyway, so the local credentials are useless without manual intervention.

What gets removed locally

removeHiveCastHostLink() in mx-cli/src/utils/hivecast-link-store.ts:578-596:

fs.rmSync(paths.linkPath, { force: true });
updateHiveCastDefaultRuntimePolicies(paths.matrixHome, localDefaultRuntimeScope(paths.matrixHome));
const hostConfigReset = resetHostConfigToLocalOwner(paths.hostConfigPath);
if (options.preserveCredentials !== true) {
  removeHiveCastCredentialFiles(paths);
}

That removes:

• <host-home>/credentials/hivecast-link.json
• <host-home>/credentials/hivecast-nats.json
• <host-home>/credentials/hivecast-host-link-token
• <host-home>/credentials.json

…and rewrites <host-home>/host.json's transport block back to local owner mode (root: COM.OPEN-MATRIX.LOCAL.AUTHORITY, embedded NATS port config). The default-runtime startup policies are flipped to the local-default scope.

<host-home>/credentials/hivecast-install.json is preserved unless --all was passed.

Sequence

# Inspect first
hivecast link-status --home /tmp/matrix-home

# Pick a variant. Local-only:
hivecast logout --home /tmp/matrix-home

# Or revoke cloud-side too:
hivecast logout --revoke-cloud-link --home /tmp/matrix-home

# Or wipe the install identity entirely:
hivecast logout --all --home /tmp/matrix-home

# Verify
hivecast link-status --home /tmp/matrix-home   # should print 'not linked'
hivecast whoami --home /tmp/matrix-home        # should exit non-zero

After disconnect

The Host is still up. Its runtimes are still running. What's gone is the linkage to the HiveCast account: the Host operates as local-owner, system.devices no longer shows this install in the cloud account, and the local NATS client uses the embedded NATS again.

The Edge UI at http://127.0.0.1:3100/apps/edge/ continues to work for local owner inspection.

Re-pair after disconnect

After --local-only or --revoke-cloud-link, re-pairing is a normal hivecast login --device invocation. The installId is preserved, so the cloud will recognize this is the same install. After --revoke-cloud-link, the previous Host Link record is revoked — re-pairing creates a fresh Host Link record (hostlink_<new>) on top of the same hostId and installId.

After --all, the next hivecast install mints a brand-new installId. The cloud will see it as a new Device.

Reverse direction: cloud-side revoke

You can also revoke a Device from the HiveCast UI without involving the Device. From the account's Devices page, click "Disconnect" on a Device row. That calls auth.hostLink.revoke cloud-side. The Device keeps running but its heartbeats start failing with HTTP 403. The Device's local hivecast-link.json is unaware of the revoke until someone runs hivecast link-status against the cloud (which will then show the link state) or runs hivecast logout to clean up locally.

See also

• Revoke grant — distinct from disconnect: revoke is about invalidating the credential, disconnect is about local cleanup.
• Pair — re-pairing after disconnect.
• Pairing / Login — the symmetric command.

Source: projects/matrix-3/packages/mx-cli/src/utils/hivecast-link-store.ts (removeHiveCastHostLink(), resetHostConfigToLocalOwner()); projects/matrix-3/packages/system-auth/src/host-auth.ts (HostLinkStore.revoke()).