Login

"Login" in HiveCast can mean two distinct things. This page disambiguates and walks through both.

The auth boundary that distinguishes them is load-bearing. The HiveCast cloud is the trust surface for account-level OAuth (Google / GitHub / Apple); the local Device is the trust surface for inference credentials and anything the Device authenticates with directly. Conflating these is the root cause of most architectural confusion. See WORKSTREAMS/thesis/THESIS.md Part 4.5 for the trust-surface doctrine.

Two senses of "login"

Sense 1: Sign into HiveCast in a browser

Open https://hivecast.ai/ (or your self-hosted equivalent), pick a provider (Google / GitHub / Apple), authenticate, land on the Devices page. Browser-side. No CLI. This is what a human does to manage their account.

This sense is owned by the platform Host running matrix-web with auth.mode: 'public-session'. The OAuth callback URL is registered with each provider against hivecast.ai's own domain.

Sense 2: Pair a Device using the CLI

Run hivecast login --device --cloud https://hivecast.ai on a local Device. Internally, this is the enrollment ceremony that links the Device to a principal — see Device pairing. It uses the same OAuth flow (the user signs in via a browser at the cloud's URL) but the resulting credential is bound to this specific Device, not a browser session.

This page focuses on sense 1 — the browser sign-in. Pairing is a separate page.

OAuth providers

Per CLAUDE.md Rule 6:

Flow	WHERE the OAuth happens	WHY
Google / GitHub OIDC	HiveCast cloud	Registered redirect URIs for hivecast.ai
Anthropic / Codex OAuth	Local HiveCast install / Factotum	Localhost redirect, credentials stay local
Domain verification	HiveCast cloud	DNS TXT check
Inference API calls	Local runtime through Factotum-owned credentials	Tokens are local

So principal identity (the user account) authenticates against the cloud. Inference credentials (Anthropic, Codex, OpenAI keys) authenticate against the LOCAL Device's Factotum and never leave the Device.

This split is the entire authority model. Per WORKSTREAMS/matrix-web/USER-FLOWS-AND-AUTH-BOUNDARIES.md, conflating these is the root cause of most architectural confusion.

What logging in does on the cloud side

When you sign into hivecast.ai:

1. The cloud's gateway (@open-matrix/system-gateway-http) issues a Google/GitHub OAuth redirect.
2. You authenticate with Google/GitHub.
3. The provider returns to hivecast.ai/api/auth/callback/<provider>.
4. system-auth exchanges the code for an OIDC id_token, looks up or creates the principal, mints a session.
5. The browser is redirected to the originally-requested URL with a session cookie.

The principal record carries:

• principalId (durable, internal)
• email (from the OIDC id_token, used to derive the legacy authority root)
• display name
• linked OAuth identities (one principal can have multiple — Google AND GitHub)

For new accounts, the authority root is derived from the durable spaceId, not from the email. For pre-existing accounts the legacy email-derived root is preserved. See Spaces.

What you see after login

The cloud platform's matrix-web shell (/apps/web/) shows:

• the navbar with your principal display name + avatar
• the dashboard surface (target state — see WORKSTREAMS/product-launch/STATUS.md)
• a Devices list (empty until you pair one)
• inference-settings access (target state — the cloud-side path)

What's stored where

After login, the cloud has:

Storage	What
system.auth actor state	the principal record
Session cookie	a short-lived id linking the browser to the principal
hivecast.ai's own NATS	bus traffic for the platform Host

Your local Device, in contrast, has nothing yet — until you pair.

What logging out does

On the cloud side, "log out" clears the browser session cookie. It does NOT revoke any paired Devices.

To fully sign out across all sessions, target state would be a "sign out of all sessions" control. Today, sessions are short-lived and bounded by an actorTimeoutMs set in host.json auth.actorTimeoutMs (or the system default).

To revoke a specific Device's link, see Device pairing → Revocation or hivecast logout --revoke-cloud-link from the Device side.

Local-Host equivalent: auth.mode: 'local-client'

If you only run a local-only Host (no cloud account), you don't "log in." The Host treats the loopback session as the local owner. host.json auth.mode: 'local-client' is the default for hivecast install.

The local owner can:

• open any of the bundled webapps
• inspect system.devices, system.runtimes, system.registry
• run hivecast invoke for any actor

The local Host is not required to be in public-session mode for this. Public-session is for the cloud-platform role.

Cloud-Host equivalent: auth.mode: 'public-session'

A Host playing the cloud-platform role (e.g. hivecast.ai or your self-hosted version) sets auth.mode: 'public-session'. This:

• accepts un-credentialed browser sessions
• routes them through the OAuth surface
• issues per-session NATS credentials after sign-in
• prevents an unauthenticated browser from publishing actors or invoking ops

public-session mode requires:

• registered OAuth provider credentials
• a session secret (HIVECAST_SESSION_SECRET env or auth.sessionSecret in host.json)
• DNS pointing at the Host
• TLS termination in front of the Host

See also

• Device pairing — how a Device gets linked to a principal.
• Security model — what credentials are issued where.
• Overview → Local host vs cloud platform — the two modes side by side.
• CLI → hivecast login / whoami / logout — the wrapper-side reference for sense 2 (Device pairing).

Source: repo-root CLAUDE.md Rule 6 (Auth boundaries); projects/matrix-3/packages/system-auth/src/host-auth.ts; WORKSTREAMS/matrix-web/USER-FLOWS-AND-AUTH-BOUNDARIES.md.