HiveCast cloud

HiveCast is the production multi-tenant deployment of Matrix at https://hivecast.ai. This page covers the topology, what runs where, and which behaviors are present-state versus target-state.

What HiveCast is, in one paragraph

HiveCast is a Matrix Host configured for the platform role. Same code as a local-user install (@open-matrix/host-service, @open-matrix/system-auth, @open-matrix/system-gateway-http, @open-matrix/matrix-web), different configuration: public Google OIDC, public TLS at hivecast.ai, public NATS hub for paired Device leaves, and the public Space URL grammar (/<spacePath>/<appName>/). The platform Host owns identity, account directory, Device pairing inventory, and routing. It does not run the user's actors. A signed-in user's chat, director, inference, and other workloads live on their own paired Device(s).

The portal thesis

Every Matrix daemon is a portal into the federation. Not just HiveCast — any daemon, any browser, any app connected to the bus.

Source: ARCHITECTURE/ARCHITECTURE-PLATFORM-TOPOLOGY.md §1.

This works exactly like the web. You don't go to "the internet hub" to browse — you open any browser and type any URL. DNS resolves the address; TCP/IP routes packets; the browser renders. Google is a discovery layer, not the routing infrastructure.

Matrix is the same. HiveCast is a Matrix daemon with a public IP and a directory. Every Matrix install can see the federation, scoped by permissions. A user opening hivecast.ai sees their stuff (routed to their home Device). A user opening their local 127.0.0.1:3100 sees the same stuff plus public realms via federation.

Production topology

Per ARCHITECTURE-PLATFORM-TOPOLOGY.md §2, the production target topology is:

HiveCast Cloud Backbone
  NATS Super-Cluster (3-5 nodes, multi-region) -- routing only, no JetStream storage
  Account resolver (control + edge cache)
  Platform actors:
    system.auth         -- principals, sessions, Spaces, namespaces, Host links
    system.devices      -- account-facing linked-Device facade
    system.runtimes     -- runtime inventory
    system.registry     -- logical mount claims
    system.gateway.http -- HTTP routes, asset serving, /api/bootstrap
  Web shell:
    matrix-web (the platform shell at /apps/web/)
    matrix-edge (the Device shell at /apps/edge/, used for local-mode and paired browsing)
  Data:
    Postgres (target) / SQLite (current) for principal, Space, namespace, Host-link records
    Gitea for the npm-compatible package registry
    Redis (target) for session cache and rate limits
        |       |
        | NATS leaf
        |
   User Device (Alice's laptop, Acme's workstation, Pi)
     Own NATS sidecar
     Own Host Service supervisor
     Own SQLite, JetStream
     Own packages
     Own inference credentials (Factotum-owned, never leave the Device)
     Outbound WSS leaf to backbone — no inbound ports

Present state — implemented:

• Single-region NATS hub for hivecast.ai. Multi-region super-cluster is target state.
• system.auth, system-gateway-http, matrix-web, and matrix-edge all run on the platform Host.
• Google OIDC works (auth.google.login, auth.google.callback in system-auth/src/index.ts:1207-1244).
• /api/bootstrap returns addressRoot, routeKey, publicNamespace, spaceId, authorityRoot for signed-in principals.
• Paired Devices connect as outbound leaves and appear in system.devices.devices.list.

Target state — not yet implemented:

• Multi-region NATS gateway. The current deployment is single-region.
• Postgres-backed principal/Space store. Today these live in JSON state files served by HostAuthStateStore.
• Redis session cache. Today sessions are validated against the local store on every request.

What runs in the cloud

Source: projects/deploy-cloud/Caddyfile.bare and projects/deploy-cloud/deploy.sh.

The hivecast.ai host runs a single container stack:

• One Host Service supervisor (the HiveCast install).
• Its bundled NATS server.
• The default runtimes: system, host-control, system-gateway-http, matrix-web, matrix-edge.
• Caddy in front for TLS termination and HTTP routing.

The Caddyfile reverse-proxies hivecast.ai, *.hivecast.ai, and the gateway's HTTP listener. Acme TLS via Let's Encrypt; subdomain routing for paired Device preview hosts is <routeKey>.hivecast.ai (used for legacy preview URLs; new code uses /<spacePath>/<appName>/ path-based routing).

deploy.sh builds the four packages that change most often (mx-cli, host-control, host-service, hivecast), rsyncs them to the live release directory, and signals the systemd-managed Host to restart its runtimes.

What does NOT run in the cloud

The HiveCast cloud Host explicitly does not own:

• A user's actors. Chat conversations, Director state, package source, inference credentials — all on the user's Device. The cloud is routing.
• Inference API tokens. Per Rule 4 (Factotum-only), inference credentials never leave the local machine. The cloud cannot make OpenAI calls on a user's behalf; it can only route a request from the user's browser to the user's Device, which makes the call locally.
• Local Device packages. Packages installed on a Device are managed by that Device's Host Service. The cloud may advertise a package via system.registry, but the bytes live on the Device.
• Federation between users. Users see each other's published (public-mounted) actors via system.registry. Private actors stay on the originating Device.

Why this matters for operators

Three operational implications:

1. Outage of the cloud Host does not stop a user's local apps. A user can keep using 127.0.0.1:3100/apps/edge/ and 127.0.0.1:3100/apps/director/ without hivecast.ai. Only cloud-routed product URLs (hivecast.ai/<spacePath>/...) and federated discovery require the cloud.
2. The cloud's threat surface is identity + routing, not user data. The state HiveCast owns is principal records, Space claims, Host-link records, NATS account JWTs. It does not own message bodies or files.
3. Scaling is horizontal at the NATS hub layer, not at the Host layer. Adding more Devices does not require more cloud Host capacity; it requires more NATS hub capacity (target: super-cluster).

See also

• Spaces — what an account claims publicly.
• Devices — linked compute participants.
• Runtime hosts — the RuntimeHostView model.
• Security: Authentication — how identity flows from Google to a session cookie.
• Reference: Database ownership — what HiveCast persists vs. what the Device persists.

Source: ARCHITECTURE/ARCHITECTURE-PLATFORM-TOPOLOGY.md §1-3 and §11. projects/deploy-cloud/Caddyfile.bare for the live HTTP routing config. projects/matrix-3/packages/system-auth/src/index.ts for the Google OIDC and Host-link plumbing that makes the platform role distinct from the local role.