HiveCast Platform

Appearance

HiveCast Platform ​

This documentation covers HiveCast — the production cloud deployment of Matrix at https://hivecast.ai. HiveCast is the multi-tenant identity, account, pairing, and routing plane for the Matrix substrate.

Audience. Platform administrators, enterprise admins, and operators running HiveCast or running their own Matrix platform instance using the same packages. End users running a single local install should start with Edge / User Admin instead. The local-Device CLI lives in HiveCast CLI / Product.

Motivation ​

The cloud platform exists because most people running a personal AI runtime do not want to also run their own NAT traversal, OAuth callback URLs, abuse handling, or domain verification. HiveCast cloud is one operating layer on top of the open substrate that handles those concerns so a Device on a home network or a small VPS can still pair to a public Space, log in with Google, and serve a stable Space URL. The substrate itself stays open and runnable on your own hardware — using the cloud is a choice about who handles the internet-facing plumbing, not a requirement of the protocol. These docs are for you if you administer a Space on hivecast.ai, operate a tenant on the cloud, or are weighing managed operation against running your own equivalent platform Host with the same packages.

Where the platform fits in the whole ​

Matrix is a typed pub/sub/RPC substrate — a federated bus where every Feed, Service, and Component is the same primitive (a typed actor with a Space-rooted address, declared accepts / emits / streams). The substrate runs across three execution tiers (local Hosts, hosted Hosts, external connectors) and is reachable through three discovery surfaces (capability catalog, registry browse, live inventory).

The HiveCast cloud platform is a vertical built on the substrate — specifically, the first big provider, the launch lighthouse, and the managed-operation layer that monetizes the open substrate (Hosted Hosts, federation hub, registry hosting, metering, billing). HiveCast is not the substrate; the substrate is open and the same packages run on a workstation install. See WORKSTREAMS/thesis/THESIS.md Parts 1 (substrate vs vertical), 5 (the verticals), and 9 (what HiveCast charges for).

What HiveCast is ​

HiveCast is a Matrix Host that plays the platform role. It is built from the same packages a local user install runs (@open-matrix/host-service, @open-matrix/system-gateway-http, @open-matrix/system-auth, @open-matrix/matrix-web), but configured for multi-user, internet-facing operation:

  • Public Google OIDC login (the local install does not serve Google OAuth).
  • Per-Device NATS user JWT credentials and per-account NATS account JWTs for paired Devices.
  • Federated NATS routing — the platform hub routes traffic between paired Device leaves and the public web shell.
  • Public Space URL grammar (https://hivecast.ai/<spacePath>/<appName>/).

HiveCast does not run user actors. A signed-in user's actors live on their own paired Device(s). HiveCast is the routing/identity/inventory plane; the work happens on the user's local install. This is the portal thesis: every Host is a portal into the federation; the cloud's job is identity, directory, and routing — not to act as the place where user code runs.

Source: ARCHITECTURE/ARCHITECTURE-PLATFORM-TOPOLOGY.md §1 (Portal Thesis), §2 (Production Topology), §11 (Current State vs Target State).

Bus is authority — HTTP only at boundaries ​

Per P1.43, the platform exposes only the HTTP endpoints a browser or external service cannot avoid:

  1. Browser-bootstrap credential issuance (/api/identity/bootstrap, /api/identity/nats-creds).
  2. OAuth redirects/callbacks (/oauth/google/callback, etc.).
  3. Static asset serving (/apps/<appName>/<assetPath>).
  4. NATS WebSocket upgrade (/nats-ws).
  5. Health endpoint (/healthz).
  6. Webhooks from external providers.
  7. Federation handshake (when federation lands).

Anything else (apps, devices, runtimes, mounts, packages, AI providers, agent state) lives as actors on the bus with declared accepts ops. The platform shell, Edge, the dashboard, the CLI, and federation peers all read those actors directly. HTTP read projections of those actors exist for non-bus-aware external clients (CI smoke checks, uptime monitors, third-party dashboards) — they are projections, not the authority. Doc pages that show GET /api/apps or GET /api/devices describe a projection; substrate consumers use matrix invoke system.<actor> <op> instead.

Trust surfaces and origin boundaries ​

Matrix subjects are not browser security boundaries. The platform's trust-surface doctrine, in one paragraph:

Code that HiveCast did not author does not run inside the HiveCast control-plane origin (hivecast.ai). Untrusted-or-user-or-package-or-generated JavaScript runs in sandboxed iframes (preferably without allow-same-origin) or on a separate registrable domain (hivecast.site is the planned target; PSL submission is required for sibling-subdomain isolation). Federation between Spaces means typed service contracts, not arbitrary network access into a peer's private network and not foreign UI in a peer's trusted browser origin.

Hosted production must boot with policy preset standard, strict, or lockdown. The dev preset is local-only. See WORKSTREAMS/thesis/THESIS.md Part 4.5 for the full doctrine and the four operating postures.

What this docs domain covers ​

Overview ​

Concept-level explanations: HiveCast cloud, Spaces, Devices, Runtime hosts, Package deployments, Admin surfaces. Read these first to align vocabulary with the rest of this docs domain.

Accounts and Spaces ​

User accounts, organizations, Spaces, ownership, and namespace claims. Spaces are the durable unit of public identity (spacePath like alt.stories.ghost-stories.funny); they back the public URL grammar and the account-facing Devices facade.

Devices ​

The platform's view of paired Devices: pairing, grants, inventory, disconnect/unlink, and health. A Device is a linked compute participant — laptop, workstation, server, VM, container, phone. The platform stores Host Link records and surfaces them through system.devices.

Deployments ​

Deployment profiles, Runtime hosts, package versions, rollouts, and rollback. Most of this section is target state — the platform-side rollout/profile machinery is being designed in lockstep with P1.40, P1.41, and P1.42.

Security ​

Authentication (Google OIDC, Host-link bearer tokens), authorization model, capability tokens (bus tokens), secrets, and audit logs. Concrete code references throughout.

Platform Admin ​

The largest section. Documents the target admin dashboard — the cloud-side equivalent of Edge for the platform operator. Many of these pages are explicitly target state; the present state is documented in Admin surfaces.

Reference ​

Platform APIs (the closed-list HTTP boundaries plus the bus actor surfaces), database ownership, and operational runbooks. Cross-references to source code.

Five-minute orientation ​

bash
# What is in the bus catalog right now (from any signed-in operator session,
# loopback or public Host).
matrix invoke system.catalog list '{}'

# What Devices are linked to a principal.
matrix invoke system.devices devices.list \
  '{"principalId":"p_xxx","includeOffline":true}'

# What runtimes are registered in the platform Host.
matrix invoke system.runtimes runtimes.list '{}'

# Resolve a public Space path.
matrix invoke system.auth auth.namespace.resolve \
  '{"routeKey":"alt.stories.ghost-stories.funny"}'

# HTTP — the closed-list boundaries only:
curl -fsS https://hivecast.ai/healthz
curl -fsS https://hivecast.ai/api/identity/bootstrap   # browser-tab credential issuance
# every other "what is on the platform?" question goes through `matrix invoke`.

Present state vs target state ​

Every page in this domain follows this convention:

  • Present state — implemented. Behavior backed by source code at the cited paths. Verifiable by matrix invoke against a live HiveCast install or by browser inspection.
  • Target state — not yet implemented. Marked at the top of the page. Sourced from WORKSTREAMS/. Documented for navigation continuity and design review, not as instructions for operators.

What works today on hivecast.ai (per WORKSTREAMS/loose-ends/INDEX.md and the auto-memory ledger):

  • Google OIDC login via system.auth's auth.google.login and auth.google.callback ops.
  • /api/identity/bootstrap returning addressRoot, routeKey, publicNamespace, spaceId, authorityRoot for a signed-in principal.
  • The dashboard at /apps/web/#dashboard showing linked Devices, runtime hosts, runtime counts, and per-app route plans (Chat, Director, Edge, Inference Settings).
  • Device pairing through the auth.device.* and auth.pair.* ops, returning per-Device NATS JWT credentials with the principal account seed staying server-side.
  • Host Link revoke through auth.hostLink.revoke (with NATS user public-key revocation).
  • Host Link credential refresh through auth.hostLink.credentials.refresh.

What is target state (loose-ends items still open):

  • The platform-admin dashboard suite (deployments, rollouts, audit logs UI, billing). The data is in system.auth and system.devices; the operator-facing UI is not built.
  • DeploymentInstance as a first-class registry citizen (P1.42).
  • Domain-verified Spaces (DNS TXT proof; only self-claimed space.<spacePath> exists today).
  • Audit log export and retention controls.
  • Multi-region NATS super-cluster (single region today).
  • hivecast.site purchase + Public Suffix List submission for v3 third-party Matrix pages.

Sister docs ​

Source: ARCHITECTURE/ARCHITECTURE-PLATFORM-TOPOLOGY.md is the SSOT for platform architecture. WORKSTREAMS/thesis/THESIS.md is the SSOT for product framing and sequencing. WORKSTREAMS/product-launch/HIVECAST-DEVICE-ENROLLMENT-SPEC.md is the SSOT for Device pairing semantics. WORKSTREAMS/product-launch/CONSTRAINTS.md lists the C1-C27 constraints every product page must satisfy. WORKSTREAMS/loose-ends/items/P1.43-http-api-reduction-bus-is-authority.md is the SSOT for the HTTP-boundary rule.