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.
MSO CLI
The browser UI at your instance's domain is one frontend, not the product. mso
reaches the same /api surface from a shell, so every feature is scriptable.
scripts/install.sh verifies and launches scripts/install-core.sh, which symlinks bin/mso to ~/.local/bin/mso. To install it by
hand from a checkout:
ln -s "$PWD/bin/mso" ~/.local/bin/mso
eval "$(mso completion bash)" # optional: tab completion
First run
mso doctor # deps, HTTPS/login origin, service, session, device — names what broke
mso doctor --fix # safe local repairs; never changes DNS/TLS/firewall/credentials
mso device pending # after a browser tries to log in, approve it from here
The CLI signs in with OS_LOGIN_PASSWORD from your .env.local and its own
device id (~/.mso/cli.device.id), which you approve once:
mso device approve "$(cat ~/.mso/cli.device.id)" "mso cli"
Browser sign-in must use HTTPS, except for loopback development/access such as
http://localhost:4005. Plain http://<server-ip>:4005 may answer health/API requests,
but the browser cannot retain MSO's Secure session cookie there. Pair the device on its final
HTTPS/localhost origin; mso doctor reports this explicitly.
Device and service commands work even while the service is down — that is on purpose, because those are exactly the commands you need when it is.
Reference
Manef Shell OS — drive the whole cockpit from the shell.
Usage: mso [options] <command> [args]
The configured MSO public origin is only ONE frontend. Everything it can do is a call to the
same /api surface, so this CLI reaches every feature without a browser.
Auth = signed session cookie (password + approved device role), cached in a jar.
Options:
--base <url> API base to talk to (default http://127.0.0.1:4005)
--env <file> Env file to source for secrets (default <repo>/.env.local)
-h, --help Show this help, or `mso <command> --help` for one command
-v, --version Show version
Commands:
Hint: commands suffixed with * have subcommands. Run `mso <command> --help`.
Files
ls [path] List a directory (default ~)
cat <path> Read a text file
raw <path> Stream a file's raw bytes to stdout (images, video, any blob)
share <id> Download an authenticated temporary-link artifact to stdout
write <path> <text> Write a file
mkdir <path> Create a directory
rm <path> Delete, recursively
mv <from> <to> Move or rename
cp <from> <to> Copy
zip <base> <name…> Zip entries of <base> to stdout (redirect it to a .zip)
upload <local> <dst> Upload a local file into <dst> (the dir must already exist)
search <q> [root] Find DIRECTORIES whose name matches (not contents; use exec+grep)
project-candidates <project> <query> [limit] [cursor] Search bounded project path/content candidates
usage [path] Disk usage
Host
exec <cmd…> Run a shell command on the host (full power)
stats CPU, memory, disk
ps Process table
units [query] systemd service inventory (system + user)
unit * logs | start | stop | restart for exact allowlisted units
packages Cached package-update visibility (never applies updates)
cleanup [--run] Preview categories; writes require preview_id, confirm and selected ids
memory-backup * Local memory snapshot: preview | history | create | verify (memory-backup --help)
status Public service status (no session needed)
health Is this CLI's session valid?
doctor [--fix|--json] Check deps, HTTPS/login origin, service, session, device; --fix repairs safe local issues, --json is read-only
agent [--continue|--resume <query>|--yolo|-yolo] Interactive MSO Agent; --oneshot <prompt> for autonomous non-TTY runs
chat Alias for agent
model [ref] Select active model from a connected provider
onboard [-y] Guided setup: AI, apps, infrastructure, skills
setup Alias for onboard
flow list|inspect|run|status|save|delete Project API/MCP automation (flow --help)
workflow * Visual/private Workflow Graph v2 CRUD + run/status (workflow --help)
integrations Named credential users, connections, sources, setup and execution
channels * Telegram/Discord channels: list, create/save/delete, test, send
agent-groups * Multi-agent discussion groups: list, show, create/save/delete, run, stop
provider * Infrastructure credentials: list | set | rm | doctor
providers * Alias for provider
gateway * Secure public HTTPS tunnel: start | status | url | stop | doctor | install | domain
domain * Automatic app subdomains: setup | status | ensure | doctor | repair-env | restore
heartbeat [once|install-cron|remove-cron] Optional fallback health/recovery
web Open the MSO browser UI (active gateway first, else loopback)
Browser
camoufox * Power the anti-detection VNC browser + read its password
Apps
apps App-store runtime apps
mapp * Managed apps; shell-list / shell-save <JSON|@file> / shell-domain <id> / shell-domain-save <id> <JSON|@file> review external connections and their public domain
term * Interactive PTY sessions (open | input | resize | stream | close)
AI + state
ai <prompt…> One turn with the assistant; prints the reply text
cockpit [project] Alfa/MSO runtime context; search with `cockpit search <query>`
threads * Conversation history: list | show | save | rename | rm
agent-sessions * Durable MSO Agent sessions: list | show | create
agent-profiles * Saved owner profiles: create | edit | clone | default | enable | disable | run
agents * Native local session agents: list | send | inbox
org * Organization chart: units, seats, reporting lines, targets
a2a * Agent-to-Agent v1 + workflow trace: list | discover | send | handoff | trace
memory * Assistant memories: list | add | rm
memory-graph [project] Knowledge graph: vault notes, project memory, agent memory
agent-vault * Separate repository progress vault: show | sync | read
config * Advanced raw AI config compatibility surface
prefs * UI preferences: show | set
federation * Batonly capability federation worker: status
models * Configure AI providers/auth; inspect model catalog
jev * JEV decision plane: status | decide | request (never executes actions)
skills * Discover host skills + curated market: available/install/remove
changelog What shipped, newest first (same text Settings → Account → About shows)
mcp * MCP tokens + live activity: list | pat <label> [scope] [ttlDays] | activity [n] | revoke <id> | revoke all
oauth <prov> * Provider sign-in (device code): start | poll
audit [n] [prefix] Audit trail, newest first (writes/exec/auth; reads are not logged)
stock <query> [page] Stock-image search (Unsplash key optional, Openverse fallback)
Devices (a local file — these work while the service is down)
device * list | pending | approve [--role] | role | revoke | revoke all --yes
devices Alias for `device list`
approve <id> [label] [--role ...] Approve a device id
revoke <id> Revoke one device
whoami This CLI's device id + session state
passwd [status] Set/change local login password with hidden prompts; status is metadata only
login Force a fresh login
logout Drop the session (server-side + local jar)
Agent run (scriptable, non-interactive)
run <prompt…> One autonomous turn, same loop as `agent`; --json, --file, --thinking
session * list | show | export | import session records without a TUI
stats --usage Token + compaction ledger for agent sessions (no cost: not recorded)
Service (local systemd)
service * status | start | stop | restart | logs
build Compile HEAD out-of-tree (safe against the live checkout)
deploy Rebuild active service with runtime quiesce/restore
update [--rebuild] Update safely from the configured channel; works even when the web runtime is down
update --auto on|off Enable/disable the nightly unattended update timer
update --channel stable|main Follow release tags (stable) or rolling main
update status Show the channel, timer state and last unattended attempt
update reconcile Preserve a local-only/diverged HEAD, then sync main to origin/main
reset [--scope config|all] Preview local factory reset; explicit token required to apply
uninstall [--purge] [--remove-code] Preview owned installation removal
tenant * Owner-only local enrollment: status | list | init | enroll | set-enabled
Escape hatches
crud * Generic resource CRUD, incl. editor documents
api * Call ANY endpoint directly
completion [shell] Completion script for bash/zsh/fish (verbs + subcommands); sh gets the bare verb list
pair [--json] Loopback/public origin, this CLI's device, pending approvals, next command
version Show version
Examples:
mso doctor
First thing to run when something is off — it names the broken layer.
mso device pending
See who typed the correct password and is waiting to be let in.
mso device approve <id> "my phone" --role viewer
Let that device sign in with least-privilege read access.
mso exec "systemctl status nginx"
Run anything on the host, as the user that owns the process.
mso camoufox start && mso camoufox session
Bring the browser up and print its one-time VNC password.
mso raw ~/shot.png > ./shot.png
Pull a binary file down; `cat` is for text.
mso mapp logs hermes
Tail a managed app's log without opening the UI.
mso api POST /api/v1/sys/cleanup
No named verb for it? Call the endpoint directly.
Environment:
MSO_BASE Same as --base
MSO_ENV Same as --env
MSO_PASSWORD Overrides OS_LOGIN_PASSWORD from the env file
MSO_DEVICE Overrides this CLI's device id (~/.mso/cli.device.id)
MSO_GATEWAY_LOCAL_URL Loopback upstream for gateway/web (default http://127.0.0.1:4005)
READ = OS_FS_READ_ROOTS; WRITE = home + ~/projects; exec = full host power.
Docs: https://github.com/rahmanef63/mso
Notes
- Every non-browser caller must send
Origin: <base>.proxy.tsblocks mutating/apirequests that cannot prove same-origin; a browser proves it withSec-Fetch-Site, and the documented fallback is anOriginwhose host matchesHost.msodoes this for you. Without it, login itself returns 403cross_origin_blocked— before any device check — which looks like an approval problem and is not. --basetargets another instance; the cookie jar is keyed by base, so switching never reuses a session minted for a different origin.raw,zipandterm streamstream to stdout — redirect them to a file.