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.
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-linuxflockinside 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:
- resolves/creates the checkout and records whether this is a fresh install;
- installs and validates
~/.local/bin/msobefore dependency installation or build, then attempts a guarded/usr/local/binlauncher when that directory is already on the invoking shell's PATH; - verifies whether the invoking shell will actually resolve
msoafter the child installer returns, and persists an idempotent~/.local/binPATH fallback for future shells; - before dependency or
.nextmutation, 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; - installs Bun/dependencies as needed;
- creates private owner auth configuration when missing; a fresh
.env.localalso enables the OAuth-protected MCP surface withOS_MCP_ENABLED=1and anexecconsent ceiling, while an existing.env.localis never rewritten during update; - 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 boundedbun install --forcerepair before failing; - installs the
mso.servicesystem unit only when systemd is really PID 1 (not merely when asystemctlexecutable exists); - enables the owner's lingering user manager needed by self-update/managed-app user units;
- activates the service only after a successful build;
- on a fresh interactive install with a verified running service, opens
/dev/ttyand launchesmso 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_DIRand 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 highestvX.Y.Zrelease tag reachable fromorigin/main.main→ rollingorigin/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:
- service is active;
- local and public
/api/healthreport the expected build id; - login works on an approved browser over HTTPS/localhost;
scripts/post-deploy-smoke.shpasses;- if UI changed, test desktop + phone portrait + phone landscape;
- if MCP changed, compare Settings → MCP signature and refresh the external app/tool snapshot;
- if managed-app origins changed, sign in again and test each explicit app hostname;
- test Viewer/Operator/Owner route behaviour on separate devices when authorization changed;
- 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.