# mountOS Skill

> Help a user build, operate, and use a self-hosted mountOS deployment.

You have the mountOS skill. mountOS is self-hosted distributed filesystem and
object-storage infrastructure: native, POSIX-compatible filesystem mounts on macOS, Linux, and
Windows over the same data, plus S3 and WebHDFS, with forks, time travel, and one-minute
versioning. The operator runs it on infrastructure they control. Every capability is in every
plan; a deployment runs the Free tier automatically at no charge for a single deployment
(currently up to 10 TiB, no license file needed), and a Business License covers more capacity
and support. You act on the user's
deployment through the Admin API and the `mountos` client, and you can inspect a running mount
through its read-only MCP connector. This file is the entry point; read the focused skill that
matches the task.

## Mental model (do not violate)

- The HUB is `appserv`, ONE per deployment, multi-tenant. It owns the admin database and the
  Hub vault, serves the Admin API at `<HUB>/api/v1/*` (Ed25519 JWT, `sub=mountos:provider`,
  `aud=mountos/appserv`), and answers client discovery. Its domain is the discovery URL every
  client is given.
- An account is the tenant. It owns its regions, users, and storages.
- A region belongs to one account and owns ONE database and ONE vault. It carries one or many
  storages, each a record pointing at an S3-compatible or Azure store (AWS S3 and R2 work as
  is), ideally in the region's locality. A volume lives in one region on exactly one storage; its
  data never crosses a region boundary at serving time.
- A region cluster is a volume-load partition INSIDE a region. It shares the region's one
  database and one vault; it is not a tenant boundary and gets no DB or vault of its own.
  `dataserv`, `gcserv`, `blockserv`, and the gateways are cluster-scoped: each serves only the
  volumes pinned to its cluster. Creating a region auto-creates its default cluster, named
  `uno` (not ready until the first cluster-scoped service registers into it).
- Client binary = `mountos`; it discovers at the HUB, then talks to the owning cluster.
- Admin SDK: `@mountos-io/admin-sdk` (TypeScript), `github.com/mountos-io/mountos-admin-sdk/go`
  (Go), `mountos-admin-sdk` (Rust crate); `createServerClient({ baseUrl, privateKey })` where `baseUrl` is your own running HUB
  (`appserv`) URL. The SDK administers a HUB that is already up; it does not stand one up. Never
  put the admin private key in a browser; for a human-driven UI the operator mints a 60-second
  token and a login URL. The SDK is the open, public connector to a running deployment's HUB
  (https://github.com/mountos-io/mountos-admin-sdk): integrate through the TypeScript, Go, or Rust
  package, call the REST API directly (`api.md`), or generate a client in any language from the
  API spec (`api.yaml`). The repo also ships `SKILL.md`, a drop-in agent skill. Full reference:
  https://mountos.io/ai/topics/admin-sdk.md.

## Skills (read the one that fits the task)

| Task | Skill |
| --- | --- |
| Deploy on AWS: provision the cloud substrate and bring up the HUB | https://mountos.io/skills/deploy.md |
| Provision and bring up a deployment: HUB, account, region, services | https://mountos.io/skills/provision.md |
| Create and use volumes: storages, volumes, keys, mount, forks, time travel | https://mountos.io/skills/volumes.md |
| Integrate over S3, WebHDFS, Kubernetes CSI, the change-event feed, and the Admin SDK | https://mountos.io/skills/integrate.md |
| Tune S3 clients and multipart uploads: AWS CLI, boto3, rclone, Cyberduck, DuckDB, Trino, PyIceberg | https://mountos.io/skills/s3.md |
| Query an iceberg lake volume from DuckDB, Trino, Spark, or PyIceberg over the REST catalog | https://mountos.io/skills/iceberg.md |
| Operate day 2: scale clusters and pools, move volumes, rotate keys, lifecycle | https://mountos.io/skills/operate.md |
| Look up a service's environment variables and what each one means | https://mountos.io/skills/env.md |

## MCP connector (inspect a running mount)

Each mountOS client ships a local, read-only MCP (Model Context Protocol) connector.
Use it to inspect a mount without touching file contents: list mounted instances, then query a
specific mount for its identity, live stats, throughput, recent deletions, recovered
(lost-and-found) files, configuration, diagnostics, and the CLI commands that operate it. It
never reads file data and never mutates state, so it is safe to run against production mounts.

## Quickstart (the happy path)

Servers need no license file. With no active license the deployment runs on the Free tier (a single
deployment, currently up to 10 TiB). To raise capacity, upload a signed license to the HUB through the
admin client or SDK (`POST /api/v1/license/load`); the HUB stores it in the admin database and serves
the current license state to every service over the heartbeat. appserv can optionally seed the first
license once from `MOUNTOS_LICENSE_PATH` on boot. A Business License covers more.

1. Stand up the HUB (`appserv` + admin DB + Hub vault); run `appserv db install` to create the admin
   schema; publish its domain.
2. Connect: `createServerClient({ baseUrl, privateKey })`.
3. `accounts.create` (the tenant), then `users.add`, then
   `regions.create({ accountId, name, dns })`, which auto-creates cluster `uno`.
4. Deploy the region's services with `REGION_CLUSTER_ID` (region derived from it); run `dataserv db install` (the
   region's data DB) on first bring-up; `uno` becomes ready.
5. `storages.create`, then `volumes.create`, then
   `POST /api/v1/volumes/:volumeId/api-keys/generate { userId }` returns `{ apiKey, apiSecret }`.
6. `curl -fsSL https://download.mountos.sh | bash`, then mount with the HUB domain and the key. The same
   data is reachable over S3 and WebHDFS.

Database schema: each service sets up its own database. `<svc> db install` creates the schema on a
fresh database (first run); `<svc> db migrate` applies pending changes to an existing one (idempotent,
safe to run from more than one instance); `<svc> db download` pre-fetches the version-matched schema and
prints its path. `appserv` owns the admin DB; `dataserv`/`gcserv` own a region's data DB. Credentials and
dialect come from the service's vault; the schema is fetched from download.mountos.sh and cached under
`~/.mountOS/downloads` (immutable, per major series).

Full walkthrough: https://mountos.io/ai/topics/getting-started.md.

## Read next

- Topic index: https://mountos.io/llms.txt
- Full agent corpus: https://mountos.io/ai/llms-full.txt
- Admin SDK, the open connector to a deployment's HUB: https://github.com/mountos-io/mountos-admin-sdk
  (`SKILL.md` drop-in agent skill, `api.md` REST reference, `api.yaml` API spec for codegen),
  full topic at https://mountos.io/ai/topics/admin-sdk.md
- Admin dashboard (open source): https://github.com/mountos-io/mountos-admin-client
- Downloads and install: https://download.mountos.sh
- Plans and licensing: the Free tier runs automatically, no download needed (self-hosted, single deployment, currently up to 10 TiB). A Business License covers more capacity and support; full terms at https://mountos.io/terms
- Support: support@mountos.io and https://mountos.io/support