> ## Documentation Index > Fetch the complete documentation index at: https://docs.monolex.ai/llms.txt > Use this file to discover all available pages before exploring further. # Monosystem > Own cross-machine authentication, gateway presence, headless supervision, scoped remote updates, frame control, file transfer, device inventory, and mailbox delivery. Monosystem is the transport and auth-owner CLI for the Monolex machine estate. It starts local headless servers, maintains the `niiad` gateway daemon, manages registered devices, controls live remote machines through `session.monolex.ai`, transfers home-confined files, and synchronizes a PTY result mailbox. *Published contract: `monosystem 0.3.21`, OpenCLIs build `2026-07-15-182726`. The executing binary, registry, and public CDN metadata agree on this release.* *Registry ownership: the canonical `docs_url` is this page, the public product homepage is `https://monolex.ai`, and Monosystem pairs with NIIA, VPNCLI, OpenCLIs, OpenCLIs Vault, Monolex Headless, and Monopty. Repository ownership remains `monolex/monolex`; no public source URL is advertised while that repository is private.* Version 0.3.21 adds plan-first, exactly scoped remote OpenCLIs updates and a per-device high-risk command gate. It preserves the auth-owner, headless, presence, file-transfer, and mailbox boundaries from 0.3.20. ## Quick Start ```bash theme={null} openclis install monosystem monosystem --version monosystem auth monosystem daemon status monosystem remote status list ``` Since the M1 auth migration, `monosystem login` owns estate authentication and writes the shared vault JWT read by the other estate binaries. ## Authentication and Devices | Command | What it does | Effect or controls | | ---------------------------- | ------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------- | | `login` | Authenticates by interactive email OTP or API key. | `--key`, `--email`, `--code`; `--evict ` atomically releases a full machine slot during OTP verification. | | `auth` | Shows vault-backed authentication status. | Read-only; does not expose the credential. | | `logout` | Performs OTP-confirmed logout, stops the daemon, and clears shared credentials. | Estate-wide local auth and runtime mutation. | | `devices` / `devices list` | Lists registered machines on the account. | Read-only; web session ids do not consume machine slots. | | `devices current` | Prints this machine's stable device id. | Read-only. | | `devices remove ` | Deactivates one registered device. | Releases a machine slot. | | `devices prune` | Deactivates stale machines while protecting the current machine. | Preview with `--dry-run`; control age with `--older-than`; require `--yes` to apply. | ## Headless and Daemon Lifecycle | Command | What it does | Important controls or boundary | | | | --------------------------------------------- | ---------------------------------------------------------- | ----------------------------------------------------------------------- | ----------------------------------------------------- | -------------------------------------------------- | | `serve` | Starts or reuses a headless terminal server. | Gateway mode creates a new owned session from the vault JWT. | | | | `serve --list` | Lists running headless instances. | Read-only runtime inventory. | | | | `serve --stop` | Reaps stale/dead instances and marks presence offline. | Skips live serving instances unless `--force` is also supplied. | | | | `serve --restart` | Replaces a live instance with a fresh one. | Interrupts work in the old headless process. | | | | `serve --cleanup` | Removes stale PTY sockets older than one day. | Local socket cleanup. | | | | `serve --local-only` | Starts local control without a gateway session or relay. | `--session-id` is accepted only in this mode. | | | | `serve --worktree ` | Creates an isolated git worktree for the session. | Repository mutation through the worktree plugin. | | | | `serve --sandbox` | Runs the session with no network and restricted writes. | OS-level sandbox boundary. | | | | `daemon run` | Runs `niiad` in the foreground; used by the OS supervisor. | Long-running gateway-presence process. | | | | `daemon start` | Installs and starts the supervised daemon. | Persistent OS service mutation. | | | | `daemon stop` | Stops and uninstalls the daemon. | Service and process mutation. | | | | `daemon status` | Reports daemon liveness and state. | Read-only runtime proof. | | | | `daemon gate status [--json]` | Reads this device's high-risk remote-command gate. | Returns `monosystem.daemon-gate-status.v1`; no gate mutation. | | | | `daemon gate enable\|disable ` | Changes one command capability for this exact device. | Security-policy mutation; remote update application requires `upgrade`. | | | | \`daemon timer install | uninstall | status\` | Manages periodic session indexing and reindex timers. | Separate scheduler lifecycle from daemon liveness. | `serve` also accepts `--device-id`, `--app-id`, `--cols`, `--rows`, and `--proxy`. Default app id is `default`, and it must match the running PTY daemon. On Windows, `daemon start` validates and mirrors the existing vault AES keys before installing its S4U Scheduled Task. The task receives a Windows-native PATH and file-storage mode without putting tokens in argv or environment. Startup succeeds only after one live daemon PID passes consecutive readiness probes; missing keys, a mismatched mirror, or an accepted task that exits early returns non-zero and names `niiad-service.log`. ## Remote Commands | Command | What it does | Current contract | | ---------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------- | | `remote status list` | Lists machine presence and reachability. | Recommended first remote query. | | `remote exec now`, `remote exec status`, or `remote exec --version` | Runs one exact, typed baseline diagnostic. | All other argv shapes are denied before child spawn and logged with values redacted. | | `remote ask ` | Sends a command through the frame relay and captures real-time terminal frames. | Interactive screen method; fast redraw output may be missed. | | `remote start ` | Requests headless startup on a remote machine. | Lifecycle mutation on the target. | | `remote cp ` | Transfers a file on a dedicated `file-transfer` DataChannel. | Single-use 60-second account+device capability; home-confined receiver paths. | | `remote update ` | Plans or applies an exact named OpenCLIs update scope. | Add `--dry-run` for a non-mutating plan; application requires the target's `upgrade` gate. | | `remote update --all` | Selects every installed non-keychain tool on the target. | `--all` cannot be combined with names; `openclis` and `openclis-vault` are always rejected remotely. | | `remote upgrade ` | Compatibility alias for `remote update niia`. | Updates NIIA only; it never means every tool. | | `remote alias` | Sets, lists, or removes exact machine aliases. | Aliases synchronize through the gateway; sync failure is non-zero. | | `remote cleanup ` | Prints the local-only cleanup procedure for that machine. | It does not pretend to perform unsafe remote lifecycle cleanup. | | `remote sessions`, `write`, `read` | Reserved typed PTY operations. | **Fail closed:** relay handles do not yet carry verified target identity or typed remote PTY ids. | | `remote tab-new`, `tab-list` | Reserved remote tab operations. | **Fail closed:** typed remote inventory/creation is not implemented. | | `remote monosystem ` | Reserved typed remote structure inspection. | **Fail closed** until a typed response exists. | Targets must be an exact machine name, exact alias, or `dev:`. Partial and ambiguous matches fail. Relative and `~/...` receiver paths resolve below the receiver home; absolute paths are accepted only below that home. Traversal and symlink escape attempts are denied. ```bash theme={null} monosystem remote status list monosystem remote exec home now monosystem remote ask home "hostname" monosystem remote cp ./report.md home:reports/report.md monosystem remote update home niia --dry-run ``` The frame relay does not turn relay handles into typed PTY ids. Use [Monopty](/ai-clis/monopty) locally on the target or authenticated SSH when exact session inventory and history are required. ## Scoped Remote Update Contract ```text theme={null} exact names or --all ↓ openclis.update-plan.v1 ↓ dry-run returns here without mutation ↓ target upgrade gate authorizes application ↓ selected tools install and affected runtime restarts ↓ terminal ACK or non-zero failure ``` The receiver always plans first. It stops and restores Headless only when `monolex-headless` is selected, and schedules its own daemon restart only after a successful `monosystem` self-update. Updating an unrelated tool interrupts neither runtime. Plan, child, restart, protocol, and 600-second terminal-ACK timeout failures return non-zero. The dry-run path neither installs nor requires the mutation gate. ## Mailbox and MCP | Command | What it does | Effect | | ------------------- | -------------------------------------------------------------- | ------------------------------------------ | | `mailbox list` | Lists recent result messages with session/source/time filters. | Read-only. | | `mailbox read ` | Reads one message. | Read-only. | | `mailbox clear` | Deletes old local entries, for example with `--before 7d`. | Destructive local mailbox mutation. | | `mailbox sync` | Synchronizes local mailbox state to cloud D1. | Network write. | | `mailbox push` | Inserts a reply or script result from `--output` or stdin. | Local message write. | | `mcp` | Runs the Monosystem MCP server over stdio JSON-RPC. | Long-running protocol mode for AI clients. | | `--mcp-schema` | Prints the current 34-command CLI-to-MCP schema. | Read-only integration contract. | ## Typed MCP Command Map `monosystem --mcp-schema` exposes 34 non-recursive command shapes. Service startup, login/logout, and the MCP server itself remain CLI lifecycle surfaces rather than recursively exposed MCP tools. | Family | Exact MCP-visible argv | | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Daemon | `daemon start`, `daemon stop`, `daemon status`, `daemon timer install`, `daemon timer uninstall`, `daemon timer status`, `daemon gate status`, `daemon gate enable`, `daemon gate disable` | | Devices | `devices list`, `devices current`, `devices remove`, `devices prune` | | Remote | `remote ask`, `remote start`, `remote status`, `remote monosystem`, `remote cp`, `remote sessions`, `remote write`, `remote read`, `remote update`, `remote upgrade`, `remote tab-new`, `remote tab-list`, `remote alias`, `remote exec`, `remote cleanup` | | Mailbox | `mailbox list`, `mailbox read`, `mailbox clear`, `mailbox sync`, `mailbox push` | | Auth | `auth` | ## Relationships | Tool | Ownership | | --------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | [NIIA](/ai-clis/niia) | Provides the unified human/agent entry point and forwards Monosystem transport, device-gate, and scoped-update commands without taking over their runtime ownership | | [Monolex Headless](/ai-clis/monolex-headless) | Owns each terminal server process and local control surface | | [Monopty](/ai-clis/monopty) | Provides typed local PTY control where remote typed PTY operations intentionally fail closed | | [VPNCLI](/ai-clis/vpncli) | Provides direct P2P shell, tunnels, mosh, and file copy; Monosystem uses the session gateway and does not require VPNCLI | | [OpenCLIs](/ai-clis/openclis) | Owns the local update plan/install contract consumed by scoped remote updates | | [OpenCLIs Vault](/ai-clis/openclis-vault) | Stores the shared estate JWT and API-key material under the auth-owner policy |