Device ownership

A Matrix Device is owned by exactly one user (the local owner) and may also be paired to one HiveCast account (the bonded principal). This page covers what each mode means and what they entitle.

Local-owner mode

The default. Anyone with loopback access to the Device's HTTP gateway is the local owner:

• Connection is over 127.0.0.1, localhost, or [::1].
• The Host's auth.identity.resolve returns { localClient: true, principalId: 'host-service' }.
• All ops bypass the per-principal ownership check.

This is intentional: the user sitting at the laptop is the local owner. They installed the Host. They can stop it, start it, run packages, install/remove things. There is no login.

Per CONSTRAINTS.md C1: "Matrix must be usable without HiveCast at all." Local-owner mode is what makes that true.

Paired mode (linked Device)

In addition to local-owner, the Device may be paired to a HiveCast account. After pairing:

• The Device has a Host Link record on the platform.
• The Device has a per-Device NATS user JWT.
• The Device sends heartbeats to hivecast.ai.
• Browser users can reach the Device via https://hivecast.ai/<spacePath>/edge/.
• Local-owner mode still works on 127.0.0.1.

Pairing is additive. Pairing does not remove local-owner. The user can still SSH to the Device and operate as local-owner; they can also reach the Device through HiveCast.

Who can do what

Action	Local-owner	Paired browser (signed-in user)	Anonymous browser
View Edge	yes	yes (paired URL)	no
Read /api/apps	yes	yes	yes (public)
Read /api/bootstrap	yes	yes	yes
Read /api/auth/me	yes	yes	returns anonymous
Read /api/identity/runtime-summary	yes	yes	no
Pair (hivecast login --device)	yes	n/a	n/a
Revoke a Host Link	yes (any link on this Host)	yes (their own only)	no
Stop/start the Host	yes	no	no
Edit host.json	yes	no	no

The local-owner gives full control. The paired user has principal-scoped access.

What pairing does NOT change about ownership

• The Device's <host-home>/ is still owned by the local OS user who installed it.
• The Host Service supervisor is still managed by hivecast CLI from the local OS account.
• Inference credentials are still Factotum-only on this Device — pairing does NOT migrate them to HiveCast.
• Local apps still run locally. The cloud only routes; the actor execution is on this Device.

Multiple paired principals (target)

Today a Device pairs to one principal. The schema does not preclude multiple Host Links bonded to different principals on one Device, but the workflows assume a single bond. Target state: clear contracts for "this Device is shared between two users" — relevant for family or small-team scenarios.

Service Devices

A Device that is not human-owned (a bot, an integration) — ownerType: 'service' on its Space — is target state. Today, a service Device is operationally a regular paired Device under a dedicated principal.

What happens when the local owner walks away

If you sell the laptop, give it away, or decommission it:

1. Remove the local install — hivecast stop, rm -rf <host-home>. The local install is gone.
2. Revoke the Host Link from HiveCast — so the Device's NATS credentials cannot be used. Use the Devices page on hivecast.ai or auth.hostLink.revoke from your other Device.
3. Confirm the Host Link is revoked in https://hivecast.ai/apps/web/#dashboard.

If you skip step 2, a future possessor of the (recovered) <host-home> could reach your Space. Always revoke when handing off a Device.

What if the Device is lost/stolen

Same as above:

1. Immediately revoke the Host Link from any other paired Device or from hivecast.ai.
2. Refresh credentials on remaining Devices (proactive — the leaked credentials should be NATS-revoked already, but proactive refresh is cheap).
3. Audit recent activity on the affected Space.

This is exactly the Operations: Resolve incident credential-leak playbook.

Headless Devices

A Device without a browser (a server, a cron host) is still owned. Local-owner is "anyone who can SSH to the OS user that owns <host-home>." Pairing is via hivecast login --device --cloud https://hivecast.ai. Edge UI is optional on a headless install — the dashboard is reachable only by remote browser via https://hivecast.ai/<spacePath>/edge/ after pairing.

Identity terminology recap

Per HiveCast Platform / Overview / Devices:

• installId — local install identity. Stable per install.
• hostId — bond identity. Created at first pair.
• hostName — mutable label. Renameable.
• deviceSlug — stable management projection key.

The local owner does not need to think about these. They are operator-internal. The product UI says "Device."

See also

• What is Edge? — role.
• Local host view — localClient detection.
• Device Management / Pair — pairing flow.
• Device Management / Disconnect — revoke flow.

Source: WORKSTREAMS/product-launch/CONSTRAINTS.md C1, C4, C7-C13. projects/matrix-3/packages/matrix-edge/src/edge-model.ts:221-237 for isLocalOwner. projects/matrix-3/packages/system-auth/src/index.ts:1311-1320 for the loopback bypass.