Skip to content

armgit / mso

Public Imported from GitHub
0

Browser-based graphical shell and control plane for a Linux server you own — real terminal, file manager, live metrics and BYOK AI in one mobile-first workspace. Next.js 16 · React 19 · node-pty · Tailwind v4 · shadcn/ui. Public alpha, self-hosted.

15.6 KB
Raw Blame

MSO documentation map

This index separates current reference from historical evidence so a dated plan cannot quietly become today's architecture documentation.

Authority order

  1. Current code and live descriptors (/api/health, GET /mcp).
  2. Generated contracts (CLI.md, CHANGELOG.md).
  3. Current reference docs below.
  4. PROGRESS.md for why/when a change shipped.
  5. Historical plans/audits for their dated context only.

Run node scripts/check-docs.mjs to validate relative links plus selected machine-verifiable facts, and node scripts/gen-comparison.mjs --check to validate comparison evidence and review freshness. The repository quality gate runs both automatically.

Current reference

Document Contract
../README.md Product overview and quickstart
QUICKSTART.md Canonical first-10-minutes tutorial: install → doctor → provider → project → safe first agent action → evidence
LAUNCH-READINESS.md 20 measurable product/launch gates, P0/P1 policy and truthful launch-label contract
LAUNCH-QA.md Concise launch answers for category, competitors, agent concepts, security, memory, recovery and readiness
SOURCE-CONCURRENCY.md One-task-one-worktree, canonical integration authority, remote protection and concurrency acceptance tests
AGENT-SECURITY.md Agent-specific threat model, tool risk classes, abuse cases and memory-admission security contract
DISASTER-RECOVERY.md 3-2-1 target, RPO/RTO objectives, backup classes and restore-drill acceptance
RELIABILITY.md Initial SLIs/SLO targets, error-budget policy, disk thresholds and release reliability contract
ARCHITECTURE.md Current runtime, shell, role, host, Agent/Local Agent/subagent, MCP and deployment architecture
GATEWAY.md Provider-neutral gateway state, health, ownership, supervisor and deployment contract
COGNITIVE-RUNTIME.md Provider-neutral MCP/session/context/tool-routing runtime and benchmark contract
AGENT-BOOTSTRAP.md Canonical first-call sequence and capability-parity matrix across CLI, MCP, and Alfa
AGENT-CODING-PLAN.md Audited coding-capability gaps in the MCP catalog, the four tools added to close them, and what stays out of scope
AGENT-PTY-DESIGN.md Why an agent-driven PTY is the highest-blast-radius tool in the catalog, and the bounds that keep it equal to exec_run
AGENT-EDIT-PREVIEW.md Why fs_edit returns the diff it applied, what a dry run promises, and how the TUI renders it
RASMIC.md Risk-aware orchestration, repo-local memory/evidence, collision detection and recipe/script promotion
MEMORY-GRAPH.md Owner Memory app: vault notes, project knowledge, agent memory, layouts and limits
AGENT-VAULT.md Separate private repository agent-progress vaults, source/data boundaries and Obsidian use
MEMORY-SAFETY.md Session-source preservation, owner cleanup previews, local memory backups, learning/discovery visibility and remaining limits
COMPARISON.md Generated product comparison methodology, evidence and notes
references/README.md One file per upstream project MSO studies or pins: license, pin, what was used and what was not copied
LICENSE-HISTORY.md Current PolyForm Noncommercial license, the permanent prior MIT grant, and open contribution questions
COMPETITIVE-ROADMAP.md Executed comparison plan, deliberate specialist boundaries and next investments
INSTALL.md Owner installation, TLS, updates, backup and uninstall
PLATFORMS.md Linux/macOS/Windows/Android/iOS support modes and machine adapters
TERMUX.md Android/Termux bootstrap through Ubuntu PRoot, repair path and verification
INFRASTRUCTURE-PROVIDERS.md Interactive MSO Agent TUI/approval/error contract plus Dokploy/Cloudflare/Hostinger/Composio credentials, tools and deployment boundary
DEVELOPMENT.md Development and release workflow
SECURITY-ASSURANCE.md Repeatable security verification lanes, public evidence, and claim boundaries
CLI.md Generated mso CLI contract
INTEGRATION-PORTABILITY.md Reviewed JSON identity transfers, encrypted credentials, SC interoperability and receiver limits
INTEGRATIONS.md Native temporary credential forms, direct HTTPS secret submission, CLI and ChatGPT Page
INTEGRATIONS-NATIVE-GOOGLE.md Native Google OAuth app/account separation, Search Console and GA4 reads, browser binding, scope and parity limits
CHANNELS.md Provider-neutral Telegram/Discord messaging, inbound verification, outbound send and Workflow bridge
PROJECT-MCP-CONNECTIONS.md Named private connections, endpoint binding and identity for modular project MCPs
BATONLY-FEDERATION.md Pull-based Batonly capability federation worker, MSO/SI-Coder execution boundary, polling, security and acceptance contract
AUTOMATION-FLOWS.md Versioned project API/MCP flows, CLI, sessions, Add MCP, assets and limits
WORKFLOW-SCHEDULES.md Interval, cron and durable one-shot scheduling semantics, missed ticks and recovery limits
WORKFLOW-GRAPH.md Private server-native Workflow Graph v2 with n8n-core triggers/flow control, versions/history, variables, integrations, visual execution and automatic learning
SHARED-GRAPH-FOUNDATION.md Canonical shared graph mechanics, feature adapters, ownership matrix and dense-graph Focus/Map interaction boundary
NAKAMA-PARITY.md Frozen Nakama scope, current implementation mappings and candidate evidence limits
N8N-PARITY.md Core n8n capability map across native Workflows, Organization, Integrations and the dedicated external n8n workspace
TUI-PARITY-PLAN.md MSO Agent TUI parity program: per-item status, the server seam each item uses, and the items deliberately refused
TUI-RENDERER-PLAN.md What the TUI is today, why a retained renderer is the only path to panels and tabs, and the M0 to M8 order that keeps every gate green
TUI-HANDOVER.md Where the TUI panel track stands, the state of the one in-progress branch, and what must be true before the alternate screen becomes the default
REA-OPENCODE-TUI.md Reverse-engineered opencode TUI study: OpenTUI engine evidence, settings/command registries, sidebar slots, tabs status, and fit for MSO
TUI-PANEL-CONTRACT.md The invariants a TUI change must not break, each with the failure that proved it: byte-identical defaults, no setting without a consumer, and why updatedAt is not an activity signal
AGENT-ACTIVITY-SIGNAL.md Why a live session activity signal cannot be derived today, the evidence per code path, and the smallest server change that would enable it
ORGANIZATION.md Owner-private organization units, seats, reporting lines, live agent bindings, and workflow routing references
MCP-HOW-TO.md Bahasa Indonesia onboarding: client connection, prompts, workflow, project MCP and troubleshooting
MCP.md MCP/OAuth internals and full external-tool security model
A2A.md A2A v1 peer discovery, delegation/task lifecycle, CLI/MCP surface and trust boundary
LOCAL-AGENTS.md Native same-host session presence, identity, mailbox delivery, TUI/tools/API and isolation
SUBAGENTS.md Same-session foreground isolated worker lifecycle, context, tool authority and limits
AGENT-PROFILES.md Saved Owner profiles, exact model binding, revision history and bounded read tasks
MCP-FEATURE-IMPLEMENTATION.md Stepwise reverse-engineering workflow for MCP tools, trusted skills and project capabilities
CHATGPT-PLUGIN.md ChatGPT custom MCP app setup, diagrams, scopes and file bridge
PLUGIN-REFERENCE-MATRIX.md Living cross-plugin architecture matrix, audit decisions and candidate generic primitives
CONNECTED-APPS.md Server-persisted external app connections, dynamic shell windows and lifecycle boundaries
MANAGED-APPS.md Hermes/OpenClaw/9Router lifecycle, jobs, backup/restore and dashboard access boundary
MANAGED-DOMAINS.md Automatic app DNS/tunnel routes, named Integrations, HTTPS verification and durable setup recovery
HERMES-INTEGRATION.md Hermes-specific integration behaviour
OPENCLAW-INTEGRATION.md OpenClaw-specific integration behaviour
9ROUTER-INTEGRATION.md 9Router immutable Docker ownership, loopback default and explicit dashboard exposure
ORCA-INTEGRATION.md Orca web bridge readiness/identity contract, private state root and shared-runtime operator limits
MODELS-INTEGRATION.md Alfa BYOK/custom/Codex provider model
SLICE-CATALOG.md Current slice/AppShell feature inventory
FRONTEND-CONTRACT.md Required UI/UX implementation rules for every feature, state lifetime, responsive layout, actions, accessibility and evidence
UI-UX-FOUNDATION.md Dynamic shell, feature and UI-kit spacing, workspace geometry and per-window feature state
TROUBLESHOOTING.md Symptom → cause → supported recovery
FAQ.md Product/security/operator boundaries
../SECURITY.md Security posture and vulnerability reporting
../CONTRIBUTING.md Contributor setup and gates
../CLAUDE.md Repository/operator implementation rules
../skills/README.md Skill catalog, trust and discovery semantics

Design contracts awaiting implementation

Document Status
EXTERNAL-FEATURE-CONTRACT.md v1 target contract for modular shell/external features; implementation status is explicit
TENANT-PREVIEW.md Disabled identity and scoped-memory runtime; live activation and full production isolation remain unimplemented
TENANT-PERSISTENCE.md Source-only durable registry, scoped memory and audit; transactions, recovery limits and operational gates
TENANT-ROLLOUT.md Finite engineering, operational approval and acceptance gates for shared-gateway multiuser deployment
NATIVE-HOST-RELAY.md Requested native macOS/Windows hosts and shared no-domain MCP relay; implementation and verification gates remain explicit

Generated/current records

Document Source
CLI.md node scripts/gen-cli-docs.mjs / bin/mso --help
CHANGELOG.md Git subjects via scripts/gen-changelog.mjs; never hand-edit
COMPARISON.md docs/comparison-data.json via scripts/gen-comparison.mjs; never hand-edit
PROGRESS.md Hand-written shipping rationale; newest first; canonical historical WHY
TESTING-HANDOFF.md Factual manual/automated test handoff; observed issues and resolved/remaining verification, never architecture authority

Historical point-in-time documents

These are retained because they contain design reasoning or finding numbers referenced by source comments. They are not current implementation contracts.

Document Status
EXTERNAL-FEATURE-AUDIT-2026-09-27.md Registry/manifest/embed source audit at 330d0cb4; migration phases remain pending
9ROUTER-MSO-APPHOST-RFC.md Historical app-host proposal; current setup/authentication contract is in MANAGED-DOMAINS and MANAGED-APPS
AUDIT-2026-08-24.md Fable/Ultracode + dynamic security audit at its named commit; includes reproduced findings and release remediation
AUDIT-2026-06-11.md Archived audit at its named date; later fixes changed many findings
R10-GLASS-AUDIT.md Point-in-time antislop R-10 glass dose audit; current rule compliance lives in the code
SHELL-FIDELITY-PLAN.md Historical design backlog/baseline; current shell design lives in code + architecture
DRAWER-MENU-BYOK-PLAN.md Historical implementation plan; phases A–C and OpenAI Codex D1 shipped; remaining ideas are not promises
OS-SETTINGS-ICON-UPDATE-DEVICE-PLAN.md Open plan, not implemented: auto-update opt-in, stable channel, Devices/Server merge, account icon picker, upload→WebP/ICO pipeline
HANDOVER.md Start here for a new session: current repo state, what shipped, what was cancelled and why, the numbers that decide things, and the traps that cost time
MSO-MIGRATION.md Phased Next→Svelte/Bun/Rust plan with its phase table: 0/1/2 shipped, 3/4 cancelled by measurement, 6 no-go, 5 not started. Authoritative over BENCH-AFTER.md
BENCH-BEFORE.md Measured baseline, 2026-10-29: bundle, LCP/TBT, hydration chain, per-app open cost and code surface, captured on an idle host as the "before" side of the Phase 4/5 comparison
BENCH-AFTER.md Measured comparison, 2026-10-30: the same eight measures two days later, side by side, including the deltas that are zero and the ones inside the noise band
MIGRATION-GATE-PLAN.md Executed migration-gate work: which §3 items landed with measurements, which were blocked and why, and the lib/ framework-import debt

Marketing/demo collateral

These files are copy/script drafts, not technical authority:

When a current-reference doc and one of these drafts disagree, update the draft or follow the current-reference doc.

Reset and removal

Maintenance, factory reset and clean uninstall · Extended workspace reference

Independent CI pilot

SELF-HOSTED-CI.md is the current manual-runner reference and Actions migration gap matrix. It does not claim completed security parity or deployment automation.