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. They serve data-plane operations for that region.

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

git clone https://github.com/mountos-io/skills.git ~/.mountos-skills
ln -s ~/.mountos-skills/deploy ~/.claude/skills/deploy

Install a service

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

# get the installer once, then reuse it for every service
curl -fsSL https://mountos.sh/install -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 · appserv only, and optional even there; the Free tier needs nothing.
#     Region services ignore it: their license arrives from the HUB heartbeat.
export MOUNTOS_LICENSE_PATH=/path/to/license

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

On Windows, install the same packages with the PowerShell installer.

Invoke-WebRequest https://mountos.sh/install/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 that the selected service needs.

Servers need no license file. With no active license, a deployment runs the Free tier automatically. A single, self-hosted Free tier deployment costs nothing. Its current capacity limit is 10 TiB. To raise the capacity, load a signed license into the HUB through the Admin API or the SDK. The HUB stores the license in the admin database. The HUB sends the current license state to every service over the heartbeat. appserv alone can seed the first license from MOUNTOS_LICENSE_PATH on boot. This step is optional. appserv accepts a single license file or a directory of license files. appserv adds the capacity of every file in the directory. Region services ignore this variable.

See Download and install and Deploy.

Control plane (set up once)

The HUB and its records are global. Set up the control plane once, no matter how large the deployment becomes.

Set up the HUB

The HUB (appserv) is the control plane. Every client and every service resolves through the HUB. Set up the HUB first. It needs its own admin database and its own Hub vault. The Set up the HUB page has the full procedure. It covers the first account, the first region, and how services trust the HUB.

Connect

Manage the control plane through the HUB's Admin API. Use the Admin SDK and point it at the HUB domain, or call the REST API 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 Admin SDK and dashboard page describes the SDK, the REST API, and the dashboard.

Each region (repeat per region)

A region stores data. Do this once per region. Everything in this section is specific to one region. Repeat the same steps for the next region.

Set up the region

Each region gets its own database and its own vault. Its storages point at one or more S3-compatible or Azure stores. Its services start and register with the HUB. The Set up a region page has the full procedure. It covers how to size dataserv and the ports each service needs. Only the HUB needs a DNS record. The Terraform package provisions a region with two make targets. See Deploy.

Create a storage, a volume, and an access key

Do the following:

• Point a storage at the object bucket.
• Create a volume on the storage.
• Generate an S3-style access key and secret key pair for 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 and secret key. The client resolves the volume's region and metadata cluster at the HUB. The client then connects to that metadata cluster for the session.

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

# all three values from the environment
export MOUNTOS_DISCOVERY_URL=https://hub.example.com
export MOUNTOS_ACCESS_KEY_ID=<access-key-id>
export MOUNTOS_SECRET_ACCESS_KEY=<secret>
mountos mount /mnt/workspace

# or pass the key id and let it prompt for the secret
mountos mount /mnt/workspace -a <access-key-id> -s

The mount point is a positional argument. The secret is never the value of a flag. -s is a switch. It reads the secret from a prompt or from standard input. The secret therefore stays out of the process list and out of the shell history.

Mount from a machine outside the deployment network. Discovery gives the client the metadata cluster's client-facing address. Most clouds do not route an instance's public address back to a machine in the same virtual network. A client inside the deployment network therefore tests a path that no real user takes.

For a permanent mount, install the shipped mount helper and add an /etc/fstab entry with an environment file, rather than a login-shell command. See the volumes skill.

A client can reach the same data 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 tools, or the hadoop-mountos Java SDK, at the local endpoint that the gateway publishes. See Clients and Download and install for the mount flags and the supported protocols.

The result

The deployment now has a HUB, an account, a region with a ready metadata cluster, a volume, and a client that mounts it. To grow the deployment:

• Add metadata clusters to spread the load of a region.
• Add regions for new localities.
• Give the HUB domain to more clients.

None of that reconfigures existing clients. They know only the HUB domain. They resolve everything else from it.