# mountOS Agent Guide

A cross-platform, forkable, time-traveling distributed filesystem over object storage.

mountOS mounts S3 and other object storage as a POSIX-compliant filesystem on macOS, Linux, Windows, and Kubernetes. It is self-hosted and distributed. Volumes also serve S3 and WebHDFS APIs and keep forks, time travel, and version history. A single deployment is free up to 10 TiB.

You are reading the agent-facing guide for mountOS. Use it to answer questions about the architecture, components, deployment, configuration, database/schema, secrets model, downloads, and support. All content here is public and intended for third-party agents.

## Topics

- **Overview** (93% covered, `topics/overview.md`). What mountOS is, a self-hosted POSIX filesystem that mounts S3 and other object storage on macOS, Linux, Windows, and Kubernetes
- **Product** (85% covered, `topics/product.md`). One-page pitch for a self-hosted POSIX filesystem over object storage, who it is for, headline capabilities, and pricing at a glance
- **Use cases** (85% covered, `topics/use-cases.md`). Workloads that run on a mountOS volume, from elastic volumes and agent sandbox storage to CI workspaces, analytics, event-driven pipelines, bulk transfer, and live media ingest
- **Architecture** (70% covered, `topics/architecture.md`). The public architecture of mountOS: HUB, regions, services, clients, and storage
- **Components** (70% covered, `topics/components.md`). The mountOS server services, clients, storage options, SDKs, and administration tools
- **Deployment** (85% covered, `topics/deployment.md`). How to deploy a self-hosted mountOS suite from official binaries (mountos.sh/install). Covers the service fleet, external dependencies, the network and HA model, the bring-up order, and the shipped client-side assets (CSI, systemd, fstab)
- **Configuration and Environment** (90% covered, `topics/configuration.md`). Configuration surface for mountOS server components, build-time identity, and the mountos client flags, grouped by component with verified defaults
- **Database and Schema** (65% covered, `topics/database-schema.md`). The database requirements for mountOS deployments
- **Vaults and Secrets** (70% covered, `topics/secrets.md`). Configure the external secret store used by mountOS services
- **Download and Install** (82% covered, `topics/download-install.md`). Public download and install guide covering installer scripts, packages, artifact layout, and source builds
- **Support and Compatibility** (85% covered, `topics/support.md`). How to obtain mountOS via the public installer, its versioning and release matrix, and protocol/S3/WebHDFS compatibility expectations
- **Getting Started (Build a System)** (78% covered, `topics/getting-started.md`). End-to-end setup from nothing to a mounted volume, standing up the HUB, provisioning with the admin SDK, creating a region and its default metadata cluster, deploying the in-region services, and creating volumes and access keys
- **Admin SDK and API** (88% covered, `topics/admin-sdk.md`). The open connector to a running deployment's HUB, Ed25519-signed Admin API access through TypeScript, Go, and Rust packages or REST, with the response envelope, pagination, error model, and client generation from api.yaml
- **Change Events** (88% covered, `topics/change-events.md`). Per-volume ordered change-event feed (create, delete, modify, rename) for general volumes, enabled by eventLogRetentionPeriod, read with mountos event as a stdout stream or a local HMAC-authenticated REST API, with capture, pagination, and consumer semantics
- **Troubleshooting** (80% covered, `topics/troubleshooting.md`). Diagnose with the built-in tooling, the mountos check command (per-platform backend verification with printed fixes), dashboards, the HUB alerts view, and a symptom-to-fix log reference for registration refusals, boot exits (env, license, vault), db install/migrate, client mount and discovery, exclusive mount refusals, gateway rejections, and change-event auth
- **Bulk and Streaming Sessions** (80% covered, `topics/bulk-streaming-sessions.md`). Bulk upload (alias push), bulk download (alias pull), and continuous HLS sink (alias record), each a resumable, daemonized job with its own status/cancel and a live entry in the admin Sessions view
- **Exclusive Mounts** (85% covered, `topics/exclusive-mounts.md`). Give one mount the only right to write a file or folder tree of a volume fork with mountos mount --exclusive, add standbys for a quick take over on another host, choose writethrough or writeback durability, and manage grants with mountos grants, ungrant, and exclusive

## Drop-in skill

For a single read-then-act entry point, load the skill at https://mountos.io/skill.md.

## How to get help

- [Download](https://mountos.sh/install)
- [Support](https://mountos.io/docs/support)
- Contact support@mountos.io