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.

11.2 KB
Raw Blame

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.ts blocks mutating /api requests that cannot prove same-origin; a browser proves it with Sec-Fetch-Site, and the documented fallback is an Origin whose host matches Host. mso does this for you. Without it, login itself returns 403 cross_origin_blocked — before any device check — which looks like an approval problem and is not.
  • --base targets another instance; the cookie jar is keyed by base, so switching never reuses a session minted for a different origin.
  • raw, zip and term stream stream to stdout — redirect them to a file.