Architecture

Control plane

The control plane sets up and runs a mountOS deployment. It stands up one HUB. Operators administer the HUB through the open-source admin SDK or the admin client. The control plane provisions accounts and regions. It deploys the in-region services that register back with the HUB. It publishes the HUB domain as the single discovery URL for every client.

How the system fits together

flowchart TD %% Legend: solid = data path, accent = authenticated admin call, muted = setup/discovery/registration vendor["Vendor (control plane) operators and in-house systems holds admin Ed25519 signing key (mints JWTs)"] sdk["mountos-admin-sdk TypeScript, Go, Rust · open source"] client["mountos-admin-client SPA + Bun backend · open source operator-run · 3-hop Ed25519 chain"] subgraph hub ["HUB (one per deployment)"] hubcore["Global HUB · appserv Admin API · /api/v1/* authn, accounts, discovery · N instances, HA"] admindb["Admin DB accounts, users, regions, metadata clusters"] vault["Hub vault signing keys · verifier set"] end subgraph region ["Data plane · Region · eu-west-1 (belongs to one account)"] subgraph uno ["Metadata cluster · uno (default, auto-created with region)"] meta["dataserv (meta) · replicated cluster"] gc["gcserv"] end more["+ metadata clusters add more to spread region's volume load"] rinfra["one Region DB · one Region vault (shared by every metadata cluster)"] blockstore["block storage · optional caching layer"] objstore["object storage · external S3-like, one or many (you point at)"] blockstore -->|"backed by"| objstore end clients["mountOS clients filesystem · S3 · HDFS · CSI discover volume at HUB domain, then pin to owning metadata cluster"] domain["The HUB domain is the single discovery URL every mountOS client is given."] vendor -->|"use directly"| sdk vendor -->|"launch via token URL"| client vendor -.->|"stand up: appserv + admin DB + Hub vault"| hubcore sdk -->|"Ed25519 JWT"| hubcore client -->|"backend to service JWT"| hubcore hubcore -.-> admindb hubcore -.-> vault vendor -.->|"deploy services: REGION_CLUSTER_ID"| region region -.->|"register · heartbeat"| hubcore clients -.->|"discover (HUB domain)"| hubcore clients -->|"data: to the owning metadata cluster"| uno domain -.- hubcore

The pieces

HUB (control nodes): one per deployment. It owns the admin database and the Hub vault. It serves the Admin API at /api/v1/*. It authenticates everything. It answers discovery.
mountos-admin-sdk(opens in new tab): the open-source connector to the HUB, in TypeScript, Go, and Rust. It authenticates to the Admin API with the admin key. Integrate through the package, the REST API (api.md), or a client that you generate from the API spec (api.yaml). The repository also includes an agent skill file, SKILL.md.
mountos-admin-client(opens in new tab): the open-source admin dashboard. It is a single-page application with a small backend. The backend terminates the authentication chain. It reverse-proxies the Admin API to the HUB.

Two ways to administer

After the HUB starts, all administration goes through its Admin API. The SDK and the dashboard both connect to the HUB's appserv URL. Both authenticate with the admin key. Neither one starts the HUB. Each administers a HUB that already runs.

SDK directly. Call mountos-admin-sdk directly to reach /api/v1/* on the HUB. The SDK needs no UI.
Admin client. Mint a short-lived token and give it to an operator as a login URL (https://<dashboard>?token=...). The admin-client backend verifies the token and issues a session. From then on, it proxies the Admin API to the HUB. The browser never holds a long-lived service credential.

Set up a deployment

The same control plane turns a fresh deployment into one that serves clients.

Set up the HUB. Deploy appserv with its admin database and Hub vault. Seed the vault with the HUB's signing key and the admin verification key. See Vault and handshake.
Administer the HUB. Reach the Admin API with the SDK directly, or launch the admin client with a short-lived token URL.
Provision. Create accounts, users, and storages. An account is the tenant. It owns its regions, users, and storages.
Create a region. This step writes only a control-plane record, the region's structure in the admin database. It starts no servers or instances. It automatically creates the region's default metadata cluster, named uno. That metadata cluster is not ready until a service registers. You provision the region's real infrastructure separately, in the next step.
Set up the region. Deploy the in-region metadata nodes with the metadata cluster's REGION_CLUSTER_ID plus the region's database and vault. They self-register with the HUB. The first registration flips uno to ready. The HUB can then assign volumes to it. You provision block storage separately. See Deploy.
Give clients the HUB domain. Publish the HUB domain as the discovery URL. Every mountOS client resolves its volume's region and metadata cluster there. It then connects to that metadata cluster for the session.

The HUB domain is the discovery URL

A client holds no region or metadata cluster address. It knows only the HUB domain. It resolves everything else from that domain at connect time. This design keeps the client configuration stable. Operators can add regions and metadata clusters. A volume can move between metadata clusters. The next discovery call simply returns the new owner. See Metadata clusters for how a volume maps to its owning metadata cluster.