Skip to content

Architecture

Control plane

The control plane brings up and runs a mountOS deployment: stand up one HUB, administer it through the open-source admin SDK or the admin client, provision accounts and regions, deploy the in-region services that register back with the HUB, and publish the HUB domain as the single discovery URL every client uses.

How the system fits together
Vendor (control plane)Vendoroperatorsand in-house systemsholds the admin Ed25519signing key (mints the JWTs)mountos-admin-sdkTypeScript, Go, Rust · open sourcemountos-admin-clientSPA + Bun backend · open sourceoperator-run · 3-hop Ed25519 chainuse directlylaunch via token URLHUB (one per deployment)Global HUBappservAdmin API · /api/v1/*authn, accounts, discoveryN instances, HAAdmin DBaccounts, users, regions, clustersHub vaultsigning keys · verifier setstand up: appserv + admin DB + Hub vaultEd25519 JWTbackend → service JWTData plane (per region)Region · eu-west-1belongs to one accountCluster · unodefault, auto-created with the regiondataserv (meta) · Raft clustergcserv+ clustersadd more to spread theregion's volume load· · ·one Region DB · one Region vault, shared by every clusterBlock storageblock volumes · peer mesh, span clustersObject storageexternal · S3-like · one or manybacked bymountOS clientsfilesystem · S3 · HDFS · CSIdiscover their volume at theHUB domain, then pin to theowning cluster for the sessiondeploy services: REGION_CLUSTER_IDregister · heartbeatdiscover (HUB domain)data: to the owning clusterThe HUB domain is the single discovery URL every mountOS client is given.data pathauthenticated admin callsetup, discovery, and registration

The pieces

  • HUB (appserv): one per deployment. It owns the admin database and the Hub vault, serves the Admin API at /api/v1/*, authenticates everything, and 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 generated from the API spec (api.yaml). The repo also ships a drop-in agent SKILL.md.
  • mountos-admin-client(opens in new tab): the open-source admin dashboard. It is a single-page app plus a small backend, which terminates the auth chain and reverse-proxies the Admin API to the HUB.

Two ways to administer

Once the HUB is running, all administration goes through its Admin API. The SDK and the dashboard both talk to the running appserv (the HUB) at its URL, and both authenticate with the admin key. Neither stands up the HUB. They administer one that is already running.

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

Bringing up a deployment

The same control plane takes a fresh deployment from nothing to serving clients.

  1. Stand up the HUB. Deploy appserv with its admin database and Hub vault, seeded with the HUB's signing key and the admin verification key. See Vault and handshake.
  2. Administer it. Reach the Admin API with the SDK directly, or launch the admin client with a short-lived token URL.
  3. Provision. Create accounts, users, and storages. An account is the tenant. It owns its regions, users, and storages.
  4. Create a region. This writes a control-plane record only, the region's structure in the admin database. It spins up no servers or instances. It auto-creates the region's default cluster, named uno, which is not ready until a service registers. The region's real infrastructure is provisioned separately, in the next step.
  5. Set up the region. Deploy the in-region services, dataserv and gcserv, with the 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, and volumes can be assigned. Block storage is provisioned separately: its block volumes span distinct clusters for fault isolation, so they are not bound to a single cluster. See Deploy.
  6. Hand out the HUB domain. Publish the HUB domain as the discovery URL. Every mountOS client resolves its volume's region and cluster there, then talks directly to that cluster for the session.

The HUB domain is the discovery URL

Clients are not configured with region or cluster addresses. They are given one thing, the HUB domain, and they resolve everything else from it at connect time. That keeps the client configuration stable as regions and clusters are added or a volume moves between clusters: the next discovery call simply returns the new owner. See Region clusters for how a volume maps to its owning cluster.

esc
↑↓ to navigate ↵ to open