Get started

mountOS separates the control plane from the regional data plane.

The control HUB manages accounts, users, regions, and service discovery. Storage and volume services run inside each region and serve regional data-plane operations.

Read https://mountos.io/skill.md

Install a service

All mountOS services use the same installation flow. The package name selects the service, and each service provides its own environment template.

# get the installer once, then reuse it for every service
curl -fsSL https://download.mountos.sh -o mountos-install
chmod +x mountos-install

# 1 · install · pick a service by package (--list to see versions, --version to pin)
./mountos-install --pkg <PACKAGE>

# 2 · env · write the variables it needs, then fill them in
<PACKAGE> env -w .env

# 3 · license · optional, only if you have a Business License certificate; the Free tier needs nothing here
export MOUNTOS_LICENSE_PATH=/path/to/license

# 4 · run · load the env and start it
set -a
. ./.env
<PACKAGE>

On Windows, the same packages are installed through the PowerShell installer.

Invoke-WebRequest https://download.mountos.sh/install.ps1 -OutFile mountos.ps1
.\mountos.ps1 -Pkg <PACKAGE>

Each service provides an env subcommand that writes a blank environment template to stdout. The template contains the variables required by the selected service.

Servers need no license file. With no active license a deployment runs the Free tier automatically, self-hosted at no charge for a single deployment (currently up to 10 TiB). To raise capacity, load a signed license into the HUB through the Admin API or SDK. The HUB stores it in the admin database and serves the current license state to every service over the heartbeat. appserv alone can optionally seed the first license once from MOUNTOS_LICENSE_PATH on boot, accepting a single file or a directory of stacked license files whose capacity is summed. Region services ignore it.

See Download and install and Deploy.

Control plane (set up once)

The HUB and the records that live on it are global. The control plane is set up once, whatever the deployment grows into.

Set up the HUB

The HUB (appserv) is the control plane every client and service resolves through, and the first service to bring up. It needs an admin database and a Hub vault of its own. The Set up the HUB page covers it end to end, including the first account and region and how services trust the HUB.

Connect

The control plane is driven through the HUB's Admin API. Use the Admin SDK, pointed at the HUB domain, or call REST directly.

bun add @mountos-io/admin-sdk   # or: npm install @mountos-io/admin-sdk

import { createServerClient } from '@mountos-io/admin-sdk'

const client = createServerClient({
  baseUrl: 'https://hub.example.com',           // the HUB domain
  privateKey: process.env.MOUNTOS_SDK_SIGNING_KEY!,  // admin signing key
})

The optional admin dashboard is a UI over the same API. The SDK, REST, and the dashboard are covered on the Admin SDK and dashboard page.

Each region (repeat per region)

A region is where data lives. Do this once per region. Everything here is region-scoped, and the same steps repeat for the next region.

Set up the region

Each region gets its own database and vault, its storages point at one or more S3-compatible or Azure stores, then its services come up and self register with the HUB. The Set up a region page covers it end to end, including sizing dataserv and which services need DNS. On Kubernetes the Helm chart wires a region in one command. See Deploy.

Create a storage, a volume, and an access key

Point a storage at the object bucket, create a volume on it, and generate an S3-style access-key / secret-key pair scoped to the volume.

const { id: storageId } = await client.storages.create({
  accountId, regionId, name: 'prod-s3', storageType: 'object',
  providerType: 's3', endpoint: 'https://s3.us-east-1.amazonaws.com',
  bucket: 'mountos-data', region: 'us-east-1',
})

const { id: volumeId } = await client.volumes.create({
  accountId, storageId, name: 'workspace', volumeType: 'general',
})

// generate an S3-style key pair scoped to the volume:
// POST /api/v1/volumes/:volumeId/api-keys/generate { userId } -> { apiKey, apiSecret }

Mount it from a client

Install the mountos client, then mount the volume with the HUB domain and the volume's access-key / secret-key pair. The client resolves the volume's region and cluster at the HUB, then connects to that cluster for the session.

curl -fsSL https://download.mountos.sh | bash   # default package is the mountos client

The same data is reachable over S3 and WebHDFS with the same key and no mount. Run mountos gateway --gateway s3,hdfs on the host that needs it, then point S3 tooling or the hadoop-mountos Java SDK at the local endpoint it publishes. See Clients and Download and install for the mount flags and surfaces.

The result

The deployment now has a HUB, an account, a region with a ready cluster, a volume, and a client mounting it. To grow, add clusters to spread a region's load, add regions for new localities, or hand the HUB domain to more clients. None of that reconfigures existing clients. They only ever know the HUB domain and resolve everything else from it.