Global topology

mountOS is hierarchical: one global HUB (appserv) sits above any number of independent regions, and each region is partitioned into one or more region clusters that run the services serving data. Clients hit the HUB once for discovery, then pin to the owning region cluster for the life of the session.

The HUB

appserv is the single global entry point for the whole deployment, and it is multi-tenant. It authenticates every request, serves the admin APIs behind the Admin SDKs, holds the global account, user, region, volume, and access-key records, and answers discovery (which cluster owns this volume?). Every account lives under this one HUB. Clients talk to it for discovery and session establishment, then route directly to the region cluster that owns their volume.

The HUB maintains its own admin database, compatible with either MySQL or PostgreSQL wire protocols, and its own vault. This vault stores the HUB's signing key, the admin verification key used to validate Admin SDK signatures, and the authoritative service-verifier set used by every mountOS service to authenticate other services.

All service-to-service requests use signed JWTs and are verified against these trusted keys. Supported vault backends include HashiCorp Vault, AWS Secrets Manager, GCP Secret Manager, and Azure Key Vault. See Vault and handshake for the two-vault topology, expected fields, and per-provider configuration.

Accounts, regions, and region clusters

An account is the tenant. Each account owns its regions, its users, and its storage backends, all under the one HUB. A region belongs to exactly one account and is self-contained. It owns its own database and its own vault, and its volumes write data through the account's storages, region-scoped records that each point at an S3-compatible or Azure store, one or many per region. A volume lives in exactly one region, and its data never crosses a region boundary at serving time.

Inside a region sit one or more region clusters: volume-load pools selected per node by REGION_CLUSTER_ID. Each cluster serves only the shard of volumes pinned to it, so a region can spread its volumes across several independent service pools. This is load separation, not tenancy: the tenant is the account, one level up. Clustering does not add a database or vault tier: every cluster in a region shares that region's single database and single vault. Each region starts with one default cluster.

dataserv and gcserv are cluster-scoped, each handling only the volumes assigned to its cluster. A volume can be moved between clusters without crossing the region boundary. blockserv is the exception: its block volumes deliberately span distinct region clusters for fault isolation, so a block storage is not pinned to one cluster.

Services in a region cluster

• dataserv: the metadata backbone. Holds the directory tree, forks, versions, and ACLs, and serves the binary metadata protocol to clients. One node serves all inodes for a given fork. A hot working set is cached in memory, backed by the region database.
• blockserv: block storage. A block storage is a peer mesh of up to 3 active-active block volumes, each a blockserv node with its own attached volume, placed in a distinct region cluster for fault isolation. Block volumes replicate bidirectionally with no primary, failover, or replica hierarchy. Its public API is the block protocol, not S3: clients discover block volumes through appserv, so blockserv needs no DNS. Object storage stays the durable source of truth, and each block volume caches parts on a raw block device. The client data plane listens on BLOCK_PORT, with a separate port for peer replication.
• gcserv: housekeeping. Collects orphaned data, prunes forks past the retention floor, and clears secrets of deactivated volumes after their grace period. Cluster-scoped like the rest: it runs as its own pool per cluster, scaled independently of the serving path.

S3 and WebHDFS are protocol surfaces of the mountos client, bound to the one volume the client is authenticated for. There is no multi-tenant gateway fleet to deploy. See Clients.

Underneath, the region database (MySQL or PostgreSQL wire-compatible) holds the durable copy of the tree, forks, blocks, and session state. File content lives in the S3-compatible or Azure stores the account's storages point at (AWS S3, Google Cloud Storage, Backblaze B2, MinIO, Azure Blob Storage, or an on-prem tier), one or many per region. block volumes cache parts on local block devices, backed by that same object storage.

Protocols on the wire

Discovery resolves a volume to its owning region cluster. From there, dataserv and gcserv are cluster-scoped, so a session talks only to the cluster that owns its volume.