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.

47.8 KB
Raw Blame

Installing MSO across machines

Current reference. MSO keeps one Linux host-runtime contract and adapts the machine around it. This preserves terminal/process/filesystem/gateway safety semantics while allowing the same product to run from Linux, macOS, Windows and Android machines. iOS/iPadOS is a first-class browser/PWA client surface.

0. Platform support

Machine Mode Install
Linux Native host curl -fsSL https://raw.githubusercontent.com/rahmanef63/mso/main/scripts/install.sh | bash
macOS Lima Linux guest same POSIX command; Darwin auto-routes
Windows WSL2 Linux distro iwr -useb https://raw.githubusercontent.com/rahmanef63/mso/main/scripts/install-windows.ps1 | iex
Android Termux + Ubuntu PRoot same POSIX command; Termux auto-routes
iOS / iPadOS PWA/client open the protected MSO HTTPS URL in Safari and Add to Home Screen

See PLATFORMS.md for the exact host scope and limitations.

Runtime requirements

  • canonical host runtime: Linux userspace;
  • systemd is optional for the CLI/web fallback runtime and required only for features that explicitly depend on systemd;
  • Node.js 22.12+, 24.x or 26+ inside the Linux runtime;
  • Bun for dependency installation/scripts;
  • a normal non-root runtime user;
  • enough memory/swap for a Next production build;
  • HTTPS through Tailscale Serve or a reverse proxy for normal non-localhost browser use;
  • CLI runtime tools curl, jq, GNU coreutils and util-linux flock inside the Linux runtime.

Optional Browser support additionally needs Camoufox, Xvfb, a lightweight X window manager, x11vnc, noVNC/websockify and a user systemd runtime.

1. Recommended one-command install

Run as the normal server user, not root:

curl -fsSL https://raw.githubusercontent.com/rahmanef63/mso/main/scripts/install.sh | bash

An AI agent with repository + shell access should treat that command as the public install/legacy-upgrade SSOT. A user only needs to say Install or update MSO from https://github.com/rahmanef63/mso. The agent must detect and preserve an existing install rather than creating another clone, use mso update for a current install when available, fall back to this installer for older builds that predate the updater, and finish with mso doctor. It should ask the user only for non-inferable choices/credentials; secrets belong in MSO's hidden/STDIN onboarding prompts, never CLI argv or chat transcripts.

scripts/install.sh is the public dispatcher. On Linux it downloads and verifies scripts/install-core.sh; on macOS and Termux it downloads and verifies the matching compatibility bootstrap before handing off. Git Bash/MSYS/Cygwin prints the supported PowerShell/WSL2 entrypoint. The verified payload is downloaded completely before execution, so a truncated network stream cannot look like a successful install.

The installer core:

  1. resolves/creates the checkout and records whether this is a fresh install;
  2. installs and validates ~/.local/bin/mso before dependency installation or build, then attempts a guarded /usr/local/bin launcher when that directory is already on the invoking shell's PATH;
  3. verifies whether the invoking shell will actually resolve mso after the child installer returns, and persists an idempotent ~/.local/bin PATH fallback for future shells;
  4. before dependency or .next mutation, acquires the same checkout transaction/runtime exclusion used by self-update, validates every owned gateway fallback, quiesces an active service only when it belongs to this checkout, then quiesces gateway-owned fallback runtimes while preserving their public tunnels;
  5. installs Bun/dependencies as needed;
  6. creates private owner auth configuration when missing; a fresh .env.local also enables the OAuth-protected MCP surface with OS_MCP_ENABLED=1 and an exec consent ceiling, while an existing .env.local is never rewritten during update;
  7. runs the production build through node node_modules/next/dist/bin/next build, bypassing Bun's package-bin remapper; if the Next package payload itself is absent, it performs one bounded bun install --force repair before failing;
  8. installs the mso.service system unit only when systemd is really PID 1 (not merely when a systemctl executable exists);
  9. enables the owner's lingering user manager needed by self-update/managed-app user units;
  10. activates the service only after a successful build;
  11. on a fresh interactive install with a verified running service, opens /dev/tty and launches mso onboard.

Useful flags:

--dir PATH       installation directory
--ref REF        branch/tag/ref (default main)
--port N         app port (default 4005)
--bind ADDR      listen address (default 127.0.0.1)
--no-service     build without installing the system unit
--onboard        force guided onboarding (including on an update)
--no-onboard     suppress automatic onboarding
-y, --yes        non-interactive safe defaults; no external accounts/apps/skills
--uninstall      remove the system unit; keep code + ~/.mso
-h, --help      print this contract without changing the host

Public environment equivalents are MSO_DIR, MSO_REF, MSO_PORT, MSO_BIND, and MSO_REPO. The default repository is the public canonical HTTPS URL. Existing canonical SSH origins are normalized to that public HTTPS origin before update so normal MSO maintenance never needs a GitHub username/token. A non-canonical MSO_REPO or existing fork/private origin remains its own origin/main authority and is never rewritten; it must have non-interactive credentials configured. MSO_BIN_DIR, MSO_SYSTEM_BIN_DIR, MSO_SKILL_DIR, MSO_UPDATE_STATE_DIR, and MSO_UPDATE_LOCK_TIMEOUT_SECONDS are advanced operator/test overrides rather than normal install UX; avoid them unless you are deliberately changing those boundaries.

Upgrading an older MSO install

Modern installations update through Settings → Update MSO or mso update. Releases from before those surfaces existed cannot invoke an updater they do not have. For those installations, re-run the current one-line installer exactly as if installing fresh. Before choosing $HOME/mso, it reads the active mso.service WorkingDirectory and upgrades that checkout in place. Existing .env.local credentials and ~/.mso state are preserved; onboarding does not repeat unless --onboard is supplied.

If the old install has no systemd service, pass its known checkout explicitly with --dir PATH (or MSO_DIR). The installer refuses an uncommitted checkout or unsafe concurrent update rather than resetting local work. After the bridge upgrade, normal future maintenance is simply:

mso update status
mso update
mso doctor

The public bootstrap is delivered through pipeline stdin, and the core deliberately does not make interactive setup depend on that stream. It prompts through /dev/tty. If there is no controlling terminal it never waits for input and tells the operator to run mso onboard later. Re-running the installer updates an existing installation under the same checkout-wide runtime lifecycle: a WSL/no-systemd fallback is stopped before dependency/build mutation and restored afterward, and an existing system service must belong to the same checkout before the installer may quiesce it. --no-service refuses to rebuild a checkout that is already serving through its system service. Onboarding is not repeated unless --onboard is requested.

Guided onboarding

Run or resume it at any time:

mso onboard

It first approves the local CLI device as Owner in the device allowlist (a process already running as the owning Unix account has equivalent host authority). On a loopback install it then verifies the MSO /api/health contract; when WSL has no active system service it can start the already-built Next production runtime itself, still bound to loopback, before proving the authenticated session. A dead runtime is reported as a runtime problem — it is not misreported as a device-approval failure. API keys are read with terminal echo disabled and posted from stdin; they are not placed in the CLI/curl argv.

The provider picker is loaded dynamically from MSO's pinned provider registry plus the cached models.dev catalog instead of a fixed eight-provider menu. Providers with at least one model whose catalog price explicitly reports both input and output cost as zero and supports tool calls are shown as free-capable. Unknown/missing pricing is never treated as free. OpenCode Zen is a pinned OpenAI-compatible API-key provider (https://opencode.ai/zen/v1); OpenRouter remains an API-key integration. OpenAI ChatGPT/Codex keeps its separate device OAuth path. A FREE label describes model token pricing only: provider account/key requirements and rate limits can still apply.

After onboarding, use the AI commands deliberately: mso models manages provider/API/OAuth connections without changing the active model; mso models free [provider] reads the live zero-cost catalog; mso model selects a model from providers that are already connected. mso models test validates the currently selected connection (including the ChatGPT/Codex subscription path), while mso model list [provider] shows selectable model IDs. Interactive mso model / mso models menus are arrow-key pickers: ↑/↓ moves, typing filters, Enter selects, and Esc cancels; numeric provider/model prompts are not part of the UX. Agent sessions are durable: mso --continue resumes the latest session and mso --resume <@name|index|id|title> resolves a prior session without weakening principal isolation. Inside the Agent, /session and bare /resume open a single newest-first picker directly—there is no second printed recent list. Rows show the short durable @name first, with the longer human session title plus modified …; IDs are hidden in the normal UI and retained only as an exact automation/debug escape hatch. Every fresh session receives a familiar unique name automatically. /rename <name> changes only this mention handle; /title <text> changes the longer durable description/topic, while new CLI titles remain auto-titleable from their first real user prompt.

Agent permission mode defaults to ask. mso --yolo and mso -yolo are global Agent startup flags, so they work without spelling agent (mso --continue --yolo is valid too). YOLO auto-approves write and exec calls for that process only; MSO still canonicalizes the exact payload and sends its approval digest to the server, but the interactive compact approval flow is skipped. In normal ask mode MSO shows one safe Approval needed: <tool> — <action> line; Enter opens redacted-safe exact-call details and the canonical digest, then a separate explicit allow or deny decision is required. /permission opens a native picker for ask, auto-write, or yolo; Tab on an empty Agent prompt cycles the same modes. auto-write approves writes only and retains exec confirmation. The mode is deliberately not persisted across Agent restarts/resumes.

Hermes/OpenClaw installation is optional and uses each app's existing managed-job installer. Their model/provider configuration belongs to those applications and is not implicitly filled from Alfa's credential. Selected app installs stream their job transcript until a terminal status.

The same onboarding can optionally connect Dokploy and one DNS provider (Cloudflare or Hostinger). These credentials are a separate infrastructure store, not AI-provider configuration. Secret prompts have terminal echo disabled and are posted from stdin; the model sees only masked configuration state and credential-free tool schemas. -y skips all external infrastructure credentials. Reconfigure later with mso provider set <id> and verify with mso provider doctor.

After an AI provider is connected, bare mso launches the interactive MSO Agent. The agent uses the canonical MCP tool catalog internally: reads run directly, while write/exec calls pause for terminal approval. Skill lifecycle is explicit in the slash palette and bottom telemetry footer: ◇ ready means discoverable/executable, ◆ queued means selected for the next user message, and ✓ invoked means the skill instructions were actually attached to a model turn. The terminal transcript uses full-width dividers for Assistant, Agent work, Local agent, and recoverable Error sections. The bottom composer is separated by an Input · @name divider, uses @name › as its identity prompt, and keeps mode ask|auto|yolo in the footer; Tab cycles that mode in place. /statusbar off collapses the footer to mode-only telemetry, while /statusbar on restores model/context/session details. Recoverable HTTP/API errors keep the interaction/session intact and never auto-repeat an uncertain write/exec call. The composer also follows conventional controls: Ctrl+C clears a draft, exits an empty prompt, or interrupts an active turn; Ctrl+D deletes right/exits on empty; Ctrl+L clears the screen; Ctrl+W deletes the previous word; ↑/↓ or Ctrl+P/N browse prompt history and are seeded from durable user prompts after resume; Ctrl+A/E and Ctrl+B/F navigate the line, Ctrl+U/K delete to the start/end, and Alt+B/F or Ctrl+←/→ move by word. /quit aliases /exit. Interrupted model/tool turns are rolled back from durable CLI history before the session is saved. See INFRASTRUCTURE-PROVIDERS.md for the deployment/provider boundary.

WSL2

WSL can contain systemctl while still running a non-systemd PID 1. MSO treats those as two different capabilities: the CLI is installed normally, while the background service is skipped with an explicit message. This prevents service setup from aborting before mso exists.

Without systemd, mso web is the supported local UI path: it starts the existing production build on loopback when necessary. mso gateway start adds an outbound temporary HTTPS tunnel on top of that without publishing the app port. mso update also works without the web API: it fast-forwards a clean main, installs dependencies, verifies an out-of-tree build, and builds in place while no service is active.

For the full service on WSL2, enable systemd in /etc/wsl.conf:

[boot]
systemd=true

Then exit all WSL sessions from Windows, reopen the distro, confirm ps -p 1 -o comm= reports systemd, and re-run the installer. The installer never edits WSL host configuration itself.

If the installer reports that the current shell did not already contain a reachable launcher directory, use the exact PATH command it prints for that shell; the profile change is already persisted for future shells.

If Bun 1.3.x reports could not open bin metadata file / Bun failed to remap this bin, that is a package-bin metadata failure rather than evidence that the installed Next package is absent. The supported installer does not use bun run build for the production build anymore: it invokes Next's Node entrypoint directly. The CLI has already been installed at that point, so even an unrelated build failure leaves mso -h available and the installer still exits non-zero with the failed phase. Re-running the same one-liner is the supported recovery path.

2. Network exposure

Gateway architecture, provider capabilities, external ownership, state semantics and non-systemd/container/Kubernetes examples are documented in GATEWAY.md.

The installer binds 127.0.0.1 by default. This is intentional: an authenticated MSO Owner session can execute host commands, and delegated roles still expose private server data.

For an initial connection, use a localhost tunnel:

ssh -N -L 4005:127.0.0.1:4005 you@your-server

Then open http://localhost:4005. A Secure cookie is accepted on localhost, but ordinary plain-HTTP IP/hostnames will drop it.

Public preview from a laptop / WSL (no custom domain)

Keep MSO bound to loopback. No system-wide tunnel package is required:

mso gateway doctor
mso gateway install       # optional prefetch; `start` does this automatically
mso gateway start
mso gateway url
mso web
# when finished
mso gateway stop

gateway start installs only the reviewed Cloudflare binary pinned by exact release URL + SHA-256 in security/gateway-artifacts.env, then creates an outbound Quick Tunnel to 127.0.0.1:4005; it never changes the application bind to 0.0.0.0. The tool cache is user-local and the tunnel is run with Cloudflare auto-update disabled. The tunnel process also receives a scrubbed environment rather than inheriting MSO login/session/BYOK secrets from the application shell. If systemd is unavailable (common on WSL), it may start the already-built Next production runtime itself, still on 127.0.0.1, and records whether that process is gateway-owned. gateway stop terminates only recorded identities: Cloudflared is matched by PID/start-time/executable/exact argv, while the Next fallback uses PID/start-time/Node executable plus a random runtime-instance nonce echoed by /api/health so Next's mutable process title cannot confuse ownership. After TERM/SIGKILL, MSO re-verifies that the exact recorded process identity disappeared before deleting lifecycle state; an unverified survivor leaves state intact and the stop fails closed. User-facing gateway stop also takes the checkout update transaction lock before the gateway lifecycle lock, so an in-flight update/installer must finish its runtime restore first; the operator's later stop is therefore final instead of being undone by stale restore inventory. Internal updater runtime-stop deliberately does not reacquire that transaction lock. Private state and logs are owner-only and scoped by the canonical checkout plus selected loopback origin. When a fallback is launched through a custom mso --env /path/file web, state stores only the validated env-file identity (canonical path, device and inode), never its secret contents. Update/installer restore revalidates that same owner/private non-symlink file and identity before sourcing it; a replacement or moved file fails closed while restore intent remains persisted instead of silently switching to .env.local. The fallback Next process uses the same held-child release handshake as Cloudflared, so neither child may execute before the parent records PID + kernel start-ticks. Gateway/update lifecycle transactions use kernel flock, which is released automatically when a process exits instead of trying to reclaim stale lock directories. A second checkout-wide shared/exclusive runtime lock blocks mso web/gateway start while an offline update is mutating .next; the updater releases that exclusive lock only after the build tree and deployment receipt are stable, then restores the runtime. If a tunnel is still alive but its local runtime died, mso gateway start reconciles/restarts the runtime, preserves the existing tunnel identity, and re-verifies the public endpoint before reporting success. Before a public tunnel is accepted, MSO snapshots the selected local {version, buildId, runtimeInstanceId} and requires the HTTPS endpoint to return the exact same identity; a same-version deployment routed from the wrong hostname is rejected.

This is intentionally labeled temporary preview. The random trycloudflare.com URL changes on restart, and Cloudflare Quick Tunnels do not support Server-Sent Events; MSO Terminal's live output uses SSE. Use a named tunnel/stable HTTPS origin for full functionality.

Do not add the random Quick Tunnel URL to OS_PUBLIC_ORIGIN: that variable is deployment authority for stable MCP/share/CSP URLs. If a stable value is already configured, temporary mode leaves it untouched and warns that generated links may continue to name the stable origin.

Stable custom domain / named Cloudflare Tunnel (recommended public path)

mso gateway domain set https://mso.example.com

The command validates a clean HTTPS origin, atomically updates only OS_PUBLIC_ORIGIN in .env.local, and prints a named-tunnel ingress example whose upstream remains loopback. Create the Cloudflare tunnel/DNS credentials using Cloudflare's official CLI, then start it without putting a token on the command line:

mso gateway start --config ~/.cloudflared/config.yml --tunnel <tunnel-id-or-name>
mso web

If another gateway is already active, stop it first with mso gateway stop. MSO refuses to silently ignore explicit named-tunnel arguments or switch tunnel modes underneath an active endpoint.

Use a dedicated named tunnel config with placeholders only:

tunnel: <tunnel-uuid>
credentials-file: /home/<user>/.cloudflared/<tunnel-uuid>.json
ingress:
  - hostname: mso.<your-domain>
    service: http://127.0.0.1:4005
  - service: http_status:404

Make ~/.cloudflared/config.yml and the credentials JSON owner-only. The config must be a regular file owned by the current user and must not be group/world-writable. MSO parses it before launch and requires exactly one ingress hostname matching OS_PUBLIC_ORIGIN that points to the configured MSO loopback port, followed by http_status:404; its credentials-file must be a private owner-owned regular file. This prevents a config intended for MSO from silently publishing other laptop services.

For Cloudflare DNS, route <mso-subdomain>.<your-domain> to <tunnel-uuid>.cfargotunnel.com as a proxied CNAME. During a nameserver cutover, it is valid to upsert the same CNAME temporarily at the old registrar/DNS provider so the stable hostname continues to resolve while NS propagation completes; move the domain nameservers to Cloudflare for reliable edge TLS/custom-hostname operation. Do not proxy mail records: MX/TXT records and mail-related CNAMEs such as autoconfig, autodiscover, and provider DKIM targets must remain DNS-only so importing a zone does not break the mail provider.

For a permanent Internet-facing control plane, add Cloudflare Access/WAF policy (or equivalent) in front of MSO in addition to MSO's password + approved-device gate. Rebuild/restart MSO after changing stable origin or split-host environment configuration. Never set OS_PUBLIC_ORIGIN to a *.trycloudflare.com preview URL.

Tailscale (private-network alternative)

Keep MSO on loopback and publish it with Tailscale Serve so the browser reaches an HTTPS origin.

Caddy/nginx/Traefik

Terminate TLS at the reverse proxy and forward to 127.0.0.1:4005. Preserve the real host and client IP headers consistently. Set OS_PUBLIC_ORIGIN=https://mso.example.com when a reverse proxy is the stable public origin; MCP discovery and managed-app CSP use it as deployment-owned authority.

Do not bind 0.0.0.0 merely because a reverse proxy exists. Bind wider only when the host firewall/network design explicitly requires it.

3. Authentication and device roles

If installing manually, copy .env.example to .env.local and set at minimum:

OS_LOGIN_PASSWORD=choose-a-strong-owner-password
OS_SESSION_SECRET=<stable random 32+ byte secret>

Open the browser on its final login origin before pairing: HTTPS in production, or http://localhost:<port> through an SSH tunnel. Do not approve a device ID obtained on a plain-HTTP server IP and then switch to an HTTPS hostname; the Secure session cookie cannot persist on the first origin, and the hostname change has a different browser-scoped device identity.

The local CLI device created by mso onboard/mso doctor --fix is approved as Owner on the host and remains the recovery path. The first correct login from a browser creates a pending device. Bootstrap the browser with the role you intend, then approve additional devices from Settings → Account → Devices or the CLI:

mso device approve <device-id> "owner laptop" --role owner
mso device approve <device-id> "read-only tablet" --role viewer
mso device role <device-id> operator
mso device role <device-id> owner     # promote a browser first approved as Viewer

Changing from localhost to the final custom HTTPS origin creates a different browser-scoped device identity, so that browser must be approved again on the new origin. Web approvals may start as Viewer; use mso device role <id> owner only after verifying the intended device.

Viewer is read-oriented; Operator adds bounded managed-app/Camoufox/service operations; Owner has write, Terminal/exec, credential, device, MCP and update authority. Web approvals default to Viewer. Role changes are resolved from the private device store on every request, so they do not wait for the session cookie to expire. The local CLI remains the recovery path if browser Owners are lost.

These roles are tied to approved devices under one deployment password and one Unix service user. They are not named-user accounts, Linux-user switching, OIDC/SSO, or tenant isolation. Shared Appearance, Theme and Quicklinks remain deployment-wide; delegated devices read/use them and Owner edits them.

Changing OS_SESSION_SECRET invalidates all existing browser sessions while leaving the device allowlist and its roles intact.

4. Filesystem roots

Read defaults cover the running checkout and ~/projects, not the whole home. File Manager opens the first allowed read root when Home is outside that boundary. Write defaults remain the owner's home/project area. Override deliberately:

OS_FS_READ_ROOTS=/path/to/project:~/projects
OS_FS_WRITE_ROOTS=~:~/projects

OS_FS_READ_ROOTS=/ permits broad read browsing subject to the process user's Unix permissions, but write roots should stay narrow. The credential denylist still blocks MSO's private state, .env*, SSH/GPG, Terraform/PyPI/Poetry/doctl/Azure and browser credential stores. Raw project .mcp.json, .npmrc, .pypirc and .netrc are denied; use the redacted MCP integration inventory for project connection metadata.

5. Service model

The installed production process is a normal systemd system unit running as the non-root owner, with its working directory set to the checkout and .env.local loaded as the environment file.

The installer also sets XDG_RUNTIME_DIR=/run/user/<uid> and enables user lingering. This is required because MSO itself controls systemd user units such as Camoufox and managed applications; without a persistent user manager those calls look like "not installed" even when the application exists.

Production health is:

GET /api/health -> {status, service, buildId, buildSha, runtimeInstanceId, uptime, version}

Service Center policy

System Monitor can inventory system and user services without extra configuration. Inventory is read-only. Journal access needs Operator/Owner, and lifecycle is disabled until an Owner adds exact entries—no wildcards—to .env.local:

OS_SERVICE_CONTROL_UNITS=user:mso.service,system:nginx.service

User-unit actions use the owner's user systemd bus. System-unit actions use the process user's normal permission by default. Only when deliberately configured may MSO invoke non-interactive sudo:

OS_SERVICE_CONTROL_USE_SUDO=1

If that flag is used, grant only the exact systemctl actions/units required; do not give the MSO user broad passwordless sudo. The application allowlist is an additional control, not a replacement for Unix/sudo policy. Advanced binary overrides (MSO_SYSTEMCTL_BIN, MSO_JOURNALCTL_BIN, MSO_SUDO_BIN) exist for unusual installations/testing and should normally stay unset.

The Updates tab is visibility-only. It reads the supported package manager's existing local cache and does not refresh repositories, install packages, or upgrade the host. Optional manager and binary overrides are documented in .env.example; normal installations should use detection.

6. Optional Browser app — Camoufox

The current Browser app is Camoufox, not the retired Playwright browser daemon. Host dependencies include xvfb, x11vnc, novnc, matchbox-window-manager, websockify and Python 3. Run python3 scripts/camoufox-artifact.py install from the canonical checkout as the service user. The repository pins Linux x86_64/arm64 release v156.0.1-beta.36, its official archive SHA-256 and the complete installed file-tree digest in scripts/camoufox-artifact.json. Installation verifies the archive before extracting into a private versioned directory under ~/.mso/private/camoufox/; it leaves profiles and session backups intact. Every launch verifies all browser files and libraries, ownership, private permissions and absence of symlinks or special files. Mutable cache discovery is removed; CAMOUFOX_BROWSER may only name the pinned installed executable. A missing or modified installation fails before opening the profile. Update both reviewed archive and tree pins deliberately for a future browser release. scripts/camoufox-vnc-service launches:

Xvfb -> matchbox window manager -> Camoufox -> x11vnc -> websockify/noVNC

The service should be a systemd user unit named camoufox-vnc.service. It is intended to stay disabled at boot, with Restart=no and a finite runtime lease; the Browser UI powers it on only when needed.

The noVNC document is never served on the cockpit origin and does not need the cockpit Domain cookie. MSO gives an authenticated Operator/Owner a short-lived viewer ticket; the separate viewer host exchanges it for a host-only HttpOnly cookie before noVNC loads. When OS_SESSION_COOKIE_DOMAIN=mso.example.com, the safe default is camoufox.example.com; with a host-only cockpit at mso.example.com, the same sibling is derived from OS_PUBLIC_ORIGIN. Provision DNS/TLS for that host, or set CAMOUFOX_VIEWER_ORIGIN to another isolated HTTPS origin. A broad two-label Domain cookie has no safely inferable sibling and therefore requires an explicit isolated viewer origin. Keep CAMOUFOX_NOVNC_URL loopback-only. The historical /camoufox-vnc/* route intentionally returns 404; the viewer gate never forwards cockpit cookies or authorization to noVNC.

Important paths/defaults:

  • persistent logged-in profile: ~/.local/share/camoufox/profiles/linkedin;
  • VNC password file: ~/.vnc/passwd;
  • rolling login/session safety snapshots: ~/.local/state/camoufox/session-backup/;
  • runtime noVNC overlay: under XDG_RUNTIME_DIR and recreated each start.

The profile can contain live Google/LinkedIn cookies. Keep the profile and session backups private (0700 parent tree) and do not add them to an ordinary broad backup without considering the account-takeover impact of a stolen cookie database.

The old os-browser/ directory that remains in this checkout is development/test tooling because it carries the Playwright dependency. It is not a production browser service and uses none of the old OS_BROWSER_* runtime configuration.

7. Optional Alfa AI

Settings → AI can store BYOK provider credentials in private host config. Common built-ins include Anthropic/OpenAI/OpenRouter/Google/Groq/xAI/DeepSeek/Mistral; custom compatible endpoints are supported and SSRF-checked.

The optional openai-codex provider uses a separate ChatGPT consumer OAuth/device flow for Alfa inference. It is unrelated to the ChatGPT MCP connector. Connect OpenAI stores that credential without changing Alfa's current provider/model; Connect & use explicitly switches. Alfa Cockpit can then switch among providers that are already connected, while credentials remain managed in Settings. See docs/MODELS-INTEGRATION.md.

8. Curated skill installation

MSO distinguishes discovery from installation. mso skills list/search/read inspect the live trusted/discovered catalog. The curated market is a smaller committed review set:

mso skills available
mso skills info ponytail
mso skills install ponytail caveman rtk -y
mso skills remove ponytail -y

Market packages are pinned in skill-market/catalog.json. The installer verifies the committed SKILL.md SHA-256 and frontmatter before copying it to ~/.mso/skills/<id> (override only for CLI/operator workflows with MSO_SKILL_INSTALL_ROOT), then writes .mso-market.json provenance. -y makes a selected normal install/removal non-interactive, but it does not overwrite a modified/local skill; replacement requires --force explicitly. Removal also refuses directories without MSO market provenance.

Ponytail and Caveman are pinned reviewed snapshots. rtk is deliberately an MSO-safe wrapper rather than the current upstream RTK Integration package: the upstream scan warns about automatically executing an unpinned remote installer and editing shell profiles. The MSO wrapper only teaches use of an already-installed RTK binary and requires a separate explicit request for system installation/hooks.

9. MCP / ChatGPT custom app

Fresh installs enable the OAuth-protected MCP surface and permit consent up to exec:

OS_MCP_ENABLED=1
OS_MCP_MAX_SCOPE=exec   # lower to write/read when full host execution is not required

This does not create an open endpoint: /mcp and OAuth discovery are live, but operational calls still require OAuth consent and a bearer. The advertised scopes are read, write, exec, and offline_access. Security default change: compromise of an exec bearer permits remote command execution as the MSO service user. Existing installs keep their current .env.local unchanged on update, so administrators who previously disabled or capped MCP remain opted down until they choose otherwise.

Use docs/CHATGPT-PLUGIN.md for ChatGPT setup and diagrams, and docs/MCP.md for the complete protocol/security model. After changing OS_MCP_MAX_SCOPE, rebuild/restart the runtime and repeat the client consent/authorization flow so ChatGPT receives the new ceiling; changing a file does not alter an already-running process or previously minted token. After changing the MCP toolset, refresh/re-scan the ChatGPT app; MSO's "Mark ChatGPT refreshed" button is only a local acknowledgement.

10. Optional managed-app dashboards

Hermes, OpenClaw and 9Router lifecycle management works without a domain. Docker does not require systemd for 9Router; on hosts without systemd, start Docker by the host-supported/manual method first, then use scripts/managed-app-9router install or mso mapp install 9router. The managed container publishes only 127.0.0.1:20128 by default. Do not default NINE_ROUTER_EXPOSE_PUBLIC=1.

Hermes/OpenClaw use user systemd units. Their prerequisite is a working user manager/bus: systemd, linger, and a valid XDG_RUNTIME_DIR=/run/user/<uid>. If that bus is unavailable, fix the prerequisite rather than accepting a half-installed app. A configured 9Router application URL is preferred for its in-shell UI. Without one, 9Router stays loopback-only unless the owner explicitly sets NINE_ROUTER_EXPOSE_PUBLIC=1 and accepts the firewall/authentication consequences. Hermes/OpenClaw remain loopback-only unless an operator adds an external route.

The safe default is no vendor dashboard on the MSO cockpit origin. To opt into split-origin embedding, configure:

NEXT_PUBLIC_MANAGED_APP_HOST_TEMPLATE={id}.mso.example.com
OS_SESSION_COOKIE_DOMAIN=.mso.example.com
OS_PUBLIC_ORIGIN=https://mso.example.com

Provision DNS/TLS only for explicit hostnames you intend to embed (hermes, openclaw, and optionally 9router) and sign out/in after changing the cookie domain. These records are optional and are not created by managed-app install. There is no supported same-origin iframe fallback. See docs/MANAGED-APPS.md and docs/9ROUTER-INTEGRATION.md.

11. Public demo mode

A public showcase must be a separate checkout/service built with:

NEXT_PUBLIC_OS_DEMO=1 bun run build

Demo mode is mock-only: no normal owner auth, no live host API, no real PTY/exec, no MCP and no API-key storage. Do not toggle demo mode in the production owner checkout.

12. Updating

Operator update

Use Settings → Update MSO or:

mso update status     # fetch + show incoming commits and labeled CLI/build identity
mso update reconcile  # preserve local-only HEAD on rescue/*, then sync main to origin/main
mso update            # preferred: update safely even if :4005 is down
mso update log

Update channel

mso update --channel stable|main (or Settings → About → Updates) chooses what an update compares against. The channel is a two-word enum; no ref, tag, path or command is ever accepted from a client or stored verbatim, and the updater resolves the Git target itself:

  • stable (default) → the highest vX.Y.Z release tag reachable from origin/main.
  • main → rolling origin/main, unchanged from earlier releases.

Because release tags can lag package.json, a checkout that is already past the newest tag reports up to date on the stable channel instead of silently following main. The only exception is a repository with no release tag at all; the status line then says no release tag exists yet and the target is origin/main. Both channels still require the checkout to be on branch main, and both still fast-forward only: if HEAD is not an ancestor of the resolved target, the update refuses with "reconcile first" rather than force-checking out a release.

Unattended updates (opt-in, off by default)

mso update --auto on    # install + enable the user timer and record the preference
mso update --auto off   # disable and delete the timer, then clear the preference
mso update status       # channel, real timer state, last unattended attempt

Enabling writes ~/.mso/prefs.json (updates.auto) and installs ~/.config/systemd/user/mso-auto-update.{service,timer} in the owner's user manager — no sudo, the same manager the manual update uses. The timer runs *-*-* 04:30:00 with RandomizedDelaySec=25m and Persistent=true. Turning it on is refused outright when the host cannot host a safe restart (wrong branch, no mso.service restart policy, no user manager), so the panel can never show "on" for a scheduler that does not exist; it also reads the real unit state, so a manually deleted timer reads "off".

An unattended run refuses, and records the reason in ~/.mso/auto-update-state.json, when the checkout is unsupported, dirty, has local commits ahead, already has an update running, when the previous two builds failed in a row, or when the incoming commits touch the updater itself (lib/host/self-update*.ts, lib/host/update-*.ts, scripts/mso-service-update, scripts/self-update.sh, scripts/self-update-auto.ts, scripts/mso-auto-update). Those last ones are applied by a human from a terminal. The pre-flight pins the commit it inspected, and scripts/self-update.sh refuses if the target moved before the build started.

MSO has two explicitly labeled version domains: the app/package version shown in Settings → Account → About and the independently versioned CLI contract shown by mso --version. The Git commit/build remains update authority. If commits changed without a CLI bump, status says N new commits on mso CLI X rather than rendering X -> X.

The updater verifies the incoming checkout/build before replacing the service. Re-running the installer on an existing checkout acquires the same checkout-scoped transaction lock before Git fetch/checkout mutation and hands that open lock FD to the post-checkout runtime lifecycle, so installer, mso update, and mso deploy cannot mutate one checkout concurrently. The lock primitive is carried by the verified installer payload itself, so older MSO checkouts that predate the current private-state helper remain upgradeable in place. A normal mso update treats fetched origin/main as the release authority: after any fast-forward, local main must equal that remote commit exactly. A clean branch that is locally ahead or diverged is refused before dependency/build mutation instead of deploying unpushed code. mso update status reports that state explicitly; mso update reconcile makes recovery explicit and lossless by preserving the previous HEAD on a timestamped local rescue/mso-update-* branch before resetting clean main to fetched origin/main. mso update --rebuild is different by design: it rebuilds the already-selected clean checkout without changing Git history. With an active mso.service it first canonicalizes the unit's WorkingDirectory and requires it to equal the checkout that invoked mso update; a secondary clone is never allowed to restart an unrelated live service. The updater then runs outside that service cgroup so it survives the restart. With no active service (including WSL without systemd), it performs the clean fast-forward/dependency/verify/build path locally. Before an offline build mutates dependencies or .next, MSO also verifies the selected loopback origin is either down or represented by gateway-owned lifecycle state; a manually started or otherwise unowned healthy MSO runtime is refused and must be stopped first. The service-active quiesce path additionally treats a healthy listener that is proven to be this checkout's own active mso.service as update-safe (runtime: service-owned): that listener is not a fallback runtime, the service lifecycle keeps it, and scripts/self-update.sh replaces it by signalling its same-UID MainPID, so there is nothing to quiesce and an interrupted service update can be retried instead of dead-ending on stale restore inventory. The offline preflight keeps the strict form and still refuses any listener that is not proven to belong to this checkout's unit. Before either the service-active or offline in-place build, update inventories every gateway state for the canonical checkout, quiesces each verified owned fallback runtime, leaves active tunnel identities intact, rebuilds, then restores every previously-owned origin with the exact env-file identity recorded for that fallback. Older owned state that predates env identity is refused before the runtime is stopped; run the same mso --env ... web/gateway path once to migrate it safely. A checkout-scoped private deployment receipt and restart marker mean a dependency/build failure after Git already reached origin/main is retried by the next ordinary mso update instead of being mislabeled "already up to date". The state is keyed by canonical checkout path, so two clones at the same SHA cannot borrow each other's receipt. One owner-only transaction lock covers every service-active or offline in-place update, from source/receipt reconciliation through gateway runtime restore and receipt write. Recovery intent is written to private state before a gateway-owned runtime is quiesced, so an interrupted post-quiesce state update stays retryable. Interactive CLI commands also show a throttled Git-backed source-update notice. When the system service is active and source is already current, the notice/status path performs a bounded loopback /api/health identity check and offers mso update --rebuild if the running build SHA differs or cannot be proven. The offline updater itself remains API-independent. A successful service finalizer log ends with UPDATE OK.

If the installed source is correct but the production build tree is inconsistent, use:

mso update --rebuild

mso deploy is the developer-facing rebuild for an already-active mso.service. It now uses the same outer checkout runtime lifecycle as self-update: verify the service belongs to this checkout, hold the exclusive mutation boundary, quiesce every owned fallback runtime, rebuild/restart the service, then restore those fallbacks. mso service start and mso service restart take the shared side of that same checkout lock and refuse while an offline update/deploy is mutating .next; they also refuse when the installed service belongs to another checkout.

No-systemd and hosted workspaces

The presence of systemctl does not mean the host runs systemd. mso doctor checks manager availability before diagnosing a system service; containers with a healthy MSO runtime are not failures merely because PID 1 is tini or another supervisor. The health check requires an actual MSO response, not an arbitrary HTTP 200. With --base pointing at a remote server, doctor does not inspect or start local units.

Use mso web --local --print to recover an installed, built loopback runtime without publishing it. mso update remains the update path; mso service and mso deploy are for installations actually controlled by the corresponding systemd unit. A detached process surviving a shell exit is not proof of restart persistence: wire the local startup command into the platform's supported startup configuration and verify a real workspace/container restart before claiming that guarantee.

Cursor's environment setup separates install (disk preparation) from start/terminals (per-run processes). Use the existing environment's startup configuration rather than modifying Cursor's private supervisor. Editor port forwarding is not by itself a verified public HTTPS origin. Only register a replacement gateway after its health identity and authenticated MCP work; keep the existing provider until that cutover is verified. See Gateway.

Developer release

After code/docs changes and verification:

bun run ship "feat(scope): describe the verified change"

The command updates the generated changelog, runs pre-push gates (including an out-of-tree production build), pushes the exact commit, then performs the in-place build/replacement and post-deploy chunk verification. When started through MCP, finalization is handed to the owner user manager so replacing MSO cannot kill its own deploy controller.

A Git push by itself is not a production deployment.

13. Rollback

Prefer an explicit known-good Git commit and the same verified rebuild/update machinery, not ad-hoc partial .next changes. Keep the old running process alive if the candidate build itself fails.

For a live chunk mismatch after the source ref is already correct, mso update --rebuild is the supported recovery path. Verify /api/health and scripts/post-deploy-smoke.sh afterward.

14. Backups and persistence

MSO owner-local state under ~/.mso/ includes:

  • approved devices and their Viewer/Operator/Owner roles;
  • AI/provider configuration;
  • MCP OAuth client/token hashes;
  • audit/activity/workflow memory;
  • managed-app snapshots under ~/.mso/backups/.

Back up ~/.mso with the same care as credentials. Managed-app snapshots can contain the managed application's secrets and are not encrypted by MSO.

Camoufox login state is not under ~/.mso; it lives in the local-share/local-state paths documented above and is even more sensitive because it can contain reusable session cookies.

Rotate/retain ~/.mso/audit.log with normal host log management. Inspect logs before sharing them because command/path context may be private.

15. Uninstall

The supported installer uninstall removes the MSO systemd unit but deliberately keeps the checkout and ~/.mso data:

curl -fsSL https://raw.githubusercontent.com/rahmanef63/mso/main/scripts/install.sh | bash -s -- --uninstall

Delete code/private state only as a separate deliberate owner action after deciding what to retain. Camoufox is a separate user service/profile and is not silently deleted by the MSO installer.

16. Verification checklist

After install/update:

  1. service is active;
  2. local and public /api/health report the expected build id;
  3. login works on an approved browser over HTTPS/localhost;
  4. scripts/post-deploy-smoke.sh passes;
  5. if UI changed, test desktop + phone portrait + phone landscape;
  6. if MCP changed, compare Settings → MCP signature and refresh the external app/tool snapshot;
  7. if managed-app origins changed, sign in again and test each explicit app hostname;
  8. test Viewer/Operator/Owner route behaviour on separate devices when authorization changed;
  9. if Service Center changed, prove inventory, bounded logs, allowlist refusal/action and cache-only package visibility.

Reset and clean uninstall

Use mso reset or mso uninstall for local, preview-first maintenance. Optional --scope all, --purge and --remove-code have distinct scopes and need an exact-plan confirmation. Read maintenance and recovery before applying. The legacy installer --uninstall keeps code and state; it is not a full purge. Bun >=1.2.15 is required for native dependency auditing.