Deploy

mountOS runs as a set of services. Deploy it on Kubernetes with the Helm chart, mount volumes into pods with the CSI driver, or run a single-host mount with systemd. This page covers the shape of a deployment and how to stand one up. For the full configuration and environment reference, see the machine-readable docs under /llms.txt.

Deployment methods

The deployment shape

A deployment has three levels. Map them before provisioning anything.

• One global HUB (appserv), with its own admin database, replicated for HA. It serves discovery and the admin APIs, and it is shared across every region.
• One or more regions. Each region has its own database, its own vault, and its own DNS, and its storages point at one or more S3-compatible or Azure stores. A region is a self-contained locality. A volume lives in exactly one region. See Regional internals.
• One or more clusters per region. A region cluster partitions volume load inside a region and shares that region's database and vault. The in-region services, dataserv and gcserv, are cluster-scoped. Block volumes run alongside them, and blockserv is not cluster-scoped.

The shared admin database, owned by the HUB, is the single source of truth for which regions and clusters exist, where each service node is, and which cluster owns each volume. In-region services reach the HUB only for discovery, region and cluster resolution, and quota replies. They otherwise talk to their own region's database.

Standing up a region or cluster

A region or cluster is a control-plane record created through the HUB's admin API, not a separate orchestration tool. The sequence is the same whether the deployment has one region or many.

1. Provision the regional infrastructure for the new locality: its database, vault, and DNS. Point storage records at an existing S3-compatible or Azure store, ideally in the same locality. The same Helm chart is reused, pointed at the new region's values.
2. Create the region through the admin API. This creates a single default cluster automatically.
3. Optionally create additional clusters in the region. Cluster names are unique within a region, and exactly one cluster is the default.
4. Bring up the in-region services with REGION_CLUSTER_ID set to the cluster's identifier, plus that region's database URL and vault credentials. They self-register with the HUB on boot.
5. The first cluster-scoped service that registers marks its cluster ready, after which volumes can be assigned to it. Create volumes against the region and cluster through the admin API.

Registration is strict. A service whose cluster id is unknown, or whose cluster is deactivated, refuses to register rather than landing on the wrong cluster. A volume can be relocated later with the move-cluster operation. See Region clusters.

How clients find their region

Clients do not need to know their region or cluster up front. Every client, mount or protocol surface, resolves its endpoint through the HUB's unauthenticated discovery endpoint:

GET /api/v1/discover/meta?access_key_id=<volume-access-key-id>

The access key encodes the volume identity, and the HUB returns the dataserv endpoints for the volume's current cluster. After a cluster move the new cluster is reflected on the next resolve.

Kubernetes with Helm

Provision the cluster and base components, copy the values template into an environment file (values.prod.yaml), set the database credentials, domains, object storage, and per-cluster REGION_CLUSTER_ID, then install:

helm upgrade --install mountos ./helm/mountos \
  -f ./helm/mountos/values.prod.yaml \
  -n mountos --create-namespace

Enable or disable individual services with a per-service flag in the values file. For a multi-region deployment, repeat the infrastructure setup once per region against that region's values, then create the region and its clusters through the admin API. In-region services register with the HUB automatically once they boot with the correct identifiers.

Kubernetes with the CSI driver

The CSI driver (csi.mountos.io) exposes mountOS volumes as ReadWriteMany PersistentVolumes, mounted through FUSE. It runs as a DaemonSet and launches the mountos client to mount each volume. A PersistentVolume references the driver, points at a dataserv metadata endpoint, and carries the volume's access-key and secret-key pair through a node-stage secret. Optional volume attributes tune caching, buffer sizes, and extended-attribute behavior.

Single host with systemd

For a single-host Linux mount, install the mountos client and use one of two unit styles. A templated service runs the client mount on start and unmount on stop, reading its environment from a per-mount file. A native .mount unit also works once the mount helper is installed with mountos mount --install-mount-helper.

Prerequisites

• A Kubernetes cluster (k3s is the reference target, with kind and full Kubernetes also supported), with kubectl and Helm 3.
• Automatic TLS (cert-manager) and an ingress controller.
• A storage class that supports dynamic provisioning, and DNS for the service domains.
• An S3-compatible or Azure store reachable from each region (existing services such as AWS S3 or Cloudflare R2 work as is), and a vault for each region plus one for the HUB. See Vault and handshake.
• For multi-region: keep the admin database with the HUB only, give each region its own database, vault, and DNS for the client-facing services it exposes, and point each region's storages at S3-compatible or Azure stores in the same locality. The HUB's identity provider and admin DNS are shared across regions.

The exact environment variables, ports, and chart values live in the machine-readable reference at /ai/llms-full.txt. For anything else, contact support.