Documentation

The basics

Install Maia OS, learn its words and meet each surface.

• Getting started

  Maia is in the architecture and consolidation phase. There is no production installer or implemented desktop product. The repository is private during pre-release.

• Concepts

  Maia OS is being built as a fully open-source personal AI operating system and application platform. A person can run a Maia node, connect Desktop, native mobile, and CLI clients, and keep control…

• Node

  @maiaos/node is the headless authority. One logical node is one brain and sovereignty domain. Clients authenticate to it and keep cache-backed views. This page is presentation only.

• CLI

  The maia CLI is the JSON-first public client of @maiaos/sdk. It is the first qualification harness for every later ADE surface. It is not a node, database client, or runtime supervisor.

• SDK

  @maiaos/sdk is the only supported node-facing product-client boundary. Desktop, native mobile, and the maia CLI consume it.

• Protocol

  @maiaos/protocol owns versioned schemas and the Maia-owned parse facade. It is not an application client, node handler, or transport. Product clients consume these contracts through @maiaos/sdk.

• Product Surfaces

  Status: planned. CLI/TUI, voice, desktop, and mobile are replaceable clients over one Node. Agents, Sessions, Routines, messages, Connections, and Swarm remain domain resources rather than branded…

• Maia OS overview

  Maia OS is an AI operating system for organizations: the software core that runs a company's agents, workflows, configuration and policy on infrastructure it controls.

• Documentation index

  Architecture documents describe target contracts, not implemented behavior. Current source status lives in the repository README, the roadmap and maia help --json.

Reference

Exact commands, contracts, events and the SDK, plus release and security policy.

• Reference

  The pages of the Maia OS documentation under Reference.

• Release, update and compatibility

  Status: design for the distribution stages RL0–RL5 in the roadmap (D-043, amended by D-132 and D-202).

• Maia security policy

  Status: pre-release. Do not disclose a suspected vulnerability, credential, transcript, artifact or exploit in a public issue or discussion.

• Maia roadmap

  As an organization, I run my agent workforce on infrastructure I control. Agents, Routines and tasks run as governed workflows across my computers, master VPS and enrolled servers.

• Summary for language models

  Maia is pre-release. Treat an operation as available only when maia help --json reports it with an implemented status and a matching registry digest.

Architecture

How the Maia Node, Swarm, Agent and clients are built and why.

• Architecture

  Status: the ownership, layers and .maia scopes below are binding. Maia is the durable control plane and product harness.

• Maia Node

  The pages of the Maia OS documentation under Maia Node.

• Maia Swarm

  The pages of the Maia OS documentation under Maia Swarm.

• Maia Agent

  The pages of the Maia OS documentation under Maia Agent.

• Maia coordinator

  Status: Project context notes are implemented. Coordinator work is Node-owned. The CLI and @maiaos/sdk are the interface; Desktop, mobile and voice only project those operations.

• Providers

  The pages of the Maia OS documentation under Providers.

• Clients

  The pages of the Maia OS documentation under Clients.

• Effect boundaries

  Status: Implemented (R0b EF2-P0, decision). Scope. Application code: every file in a workspace src/ (apps/*, packages/*, services/*) except tests (*.test.*, *.spec.*), testing/ support and…

• Skills: standard operating procedures

  Status:. This document owns what a Skill is, how one is written, pinned, kept up to date, delivered to each harness and traced.

• Team Workspaces and control Nodes

  Status: the first-owner bootstrap is a Source candidate: all five implementation-slice steps are source-implemented… A team Workspace is the shared scope of an organization on its Control Node: the…

Operations and development

Run, test, build and decide: the working notes of the Maia team.

• Maia operations

  Status: source candidate for one local Node per profile on a loopback HTTP/WebSocket listener with a bearer token, the… This document owns deployment, storage, identity, observability, recovery and…

• Maia builds Maia

  Status: planned (SH0–SH3, owner direction 22 October 2026). Maia's own development is its first production deployment.

• Development

  Status: describes the current tooling (package.json scripts, scripts/dev, scripts/quality and .github/workflows/ci.yml). Install Node 24.22.1 (.node-version) and pnpm 11.20.0, then:

• Testing policy

  Status: Implemented for the rules marked lint. Test observable behavior through the owning public interface, at the lowest boundary that can fail for the real reason: pure logic as a unit, storage…

• Scope-first source organization

  Status: approved plan for R0a (decision). Repository rules keep the authority, Effect, dependency and verification requirements. The roadmap owns current implementation status.

• Enterprise readiness plan

  Status: planned. A self-hosted product cannot hold SOC 2 or ISO 27001. Those certify the organization (vllnt): how it builds, ships, supports and runs Maia, and any hosted service.

• Feature coverage map

  This map assigns each requested product capability to the Maia slice that owns it, or marks it open or not planned. Status lives in the named roadmap entries, not here.

• Benchmarks and codebase metrics

  Status: source candidate for the first slice (decision): pnpm metrics, pnpm metrics:compare and the CI metrics job on… Every change to Maia should show what it did to size, speed and codebase…

• Decision log

  Every decision worth keeping lives here: the choice, why, the alternatives rejected, the date and links. Other documents state the resulting contract and link the entry.

Applications, packages and services

What each application, package and service in the Maia repository does.

• Applications

  Applications are replaceable clients of Maia's protocol. They do not own durable control-plane truth.

• Packages

  Shared libraries of Maia OS. Each package has one clear owner and is extracted only when at least two real consumers need it.

• Services

  The target agent execution boundary is one out-of-process worker based on official @earendil-works/pi-* packages.

Status words

Every capability in these pages carries one of five status words. A word moves only when that exact capability passes its checks on that platform.

implemented

Released through a documented public surface and covered by release checks.

source-implemented candidate

Built and tested in the Maia repository, but not released. Design partners run it from a source checkout.

planned

Decided or proposed. There is no working code to rely on, so read the plan and do not build on it.

unsupported

Deliberately not available for a named platform or version, such as a Windows host today.

deprecated

Still works for a set period, with a named replacement and a stated condition for removal.