Monosystem

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

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 <device-id>` 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 <device-id>`	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 <path>`	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 <exec\|upgrade>`	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 <target> now`, `remote exec <target> status`, or `remote exec <target> --version`	Runs one exact, typed baseline diagnostic.	All other argv shapes are denied before child spawn and logged with values redacted.
`remote ask <target> <command>`	Sends a command through the frame relay and captures real-time terminal frames.	Interactive screen method; fast redraw output may be missed.
`remote start <target>`	Requests headless startup on a remote machine.	Lifecycle mutation on the target.
`remote cp <src> <dst>`	Transfers a file on a dedicated `file-transfer` DataChannel.	Single-use 60-second account+device capability; home-confined receiver paths.
`remote update <target> <tool...>`	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 <target> --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 <target>`	Compatibility alias for `remote update <target> 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 <target>`	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 <nonlocal>`	Reserved typed remote structure inspection.	Fail closed until a typed response exists.

Targets must be an exact machine name, exact alias, or dev:<device-id>. 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.

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 locally on the target or authenticated SSH when exact session inventory and history are required.

Scoped Remote Update Contract

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 <id>`	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	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	Owns each terminal server process and local control surface
Monopty	Provides typed local PTY control where remote typed PTY operations intentionally fail closed
VPNCLI	Provides direct P2P shell, tunnels, mosh, and file copy; Monosystem uses the session gateway and does not require VPNCLI
OpenCLIs	Owns the local update plan/install contract consumed by scoped remote updates
OpenCLIs Vault	Stores the shared estate JWT and API-key material under the auth-owner policy

Get Started

Articles

So Anthropic

User Guide

Philosophy

Applied Philosophy

Architecture

Gestalt Color

Transparency

Terminal Core

Features

VariableMD

Research

CodexMono

OpenCLIs

vpncli

MonoSurf

AI-CLIs

Quick Start

Authentication and Devices

Headless and Daemon Lifecycle

Remote Commands

Scoped Remote Update Contract

Mailbox and MCP

Typed MCP Command Map

Relationships

​Quick Start

​Authentication and Devices

​Headless and Daemon Lifecycle

​Remote Commands

​Scoped Remote Update Contract

​Mailbox and MCP

​Typed MCP Command Map

​Relationships

Quick Start

Authentication and Devices

Headless and Daemon Lifecycle

Remote Commands

Scoped Remote Update Contract

Mailbox and MCP

Typed MCP Command Map

Relationships