Manef Shell OS

Your Linux server, finally usable from your phone.

Open a real terminal, manage files, inspect system health, and use AI from one private browser workspace.

Live instance · Watch Demo · Install

Manef Shell OS (MSO in the UI) is an open-source, mobile-friendly visual shell for a Linux server you own. It brings a real terminal, file manager, live system metrics, and a BYOK AI assistant into one private browser workspace without running a full remote desktop.

MSO is Public Alpha / Developer Preview software. It runs on top of Linux as a normal non-root Node process. It is not an operating system, Linux distribution, desktop environment, VPS provider, or production-grade security platform.

For a real deployment, put MSO behind Tailscale, a VPN, or a TLS reverse proxy with tight access control. Do not expose the raw app port to the public internet.

Product screenshot/video

What you can do

Control — terminal, files, and system monitor for the server you own.

• Open a real terminal — interactive PTY support for tools like vim, top, and ssh.
• Manage files — browse, upload, search, preview, rename, move, copy, zip, and delete within configured filesystem roots.
• Inspect system health — view live CPU, memory, disk, network, process, and uptime signals.
• Update itself — Settings → About shows what is on origin/main, lists the incoming commits, and runs the whole deploy (pull → verify the build out-of-tree → build → restart) from a button. The verification runs first on purpose: a commit that does not compile becomes a refusal, not an outage. The updater runs in the owner's systemd user manager and does not require passwordless sudo. Same thing from a shell: mso update run.
• Manage other apps on the box — detect, start/stop/restart, health, version, logs, and state backups for separate applications you already run (Hermes, OpenClaw, 9Router), driven through their own systemd/Docker/CLI contracts. 9Router uses its configured application domain as the in-shell dashboard when available, with public IP as the no-domain fallback. See docs/MANAGED-APPS.md.

Work — code/text editor, browser, and media tools in the same workspace.

• Edit project files — open text/code files from the file manager without context switching.
• Preview almost anything — images (including HEIC/TIFF), audio, video, PDFs, plain text, Markdown, CSV/TSV and HTML, with ← → paging through the folder. Formats no browser can render (Office, iWork, archives, installers) say so and offer the download instead of a blank frame. HTML renders in a fully sandboxed frame, never as a document on MSO's own origin.
• Keep admin context together — move between terminal, files, metrics, and browser views.

Extend — Alfa AI, modular slices, and custom apps.

• Use BYOK AI — Alfa uses credentials stored on your server, not committed to the repo.
• Drive the box from ChatGPT, Claude.ai or Cursor — an optional MCP server (OAuth 2.1 + PKCE) exposes files, system health, global project/skill discovery, ChatGPT file import and, at exec, a shell. The read/write/exec ladder is the server-side permission boundary. See the ChatGPT custom MCP app guide for setup/diagrams and MCP reference for internals.
• Add app slices — features are modular under frontend/slices/<slug>/.
• Personalize the interface — macOS, Windows, iOS, and Android shell layouts are UI preferences, not the core product.

What can you do with MSO?

Fix a server issue from your phone
Check system health, open a real terminal, inspect logs, and restart a service without opening a laptop.

Manage project files visually
Browse, upload, rename, preview, and edit files without remembering every shell command.

Work with your server in one workspace
Move between terminal, files, metrics, browser, and AI without switching between several admin tools.

Live demo

The public demo should be deployed from a separate checkout with:

NEXT_PUBLIC_OS_DEMO=1 bun run build && bun run start

Demo mode skips real login, forces mock data, blocks live host API access, and shows a permanent demo banner. Use it for Product Hunt traffic. A real owner deployment should stay behind Tailscale/VPN or a protected HTTPS proxy.

• Live instance (the maintainer's own cockpit, auth-gated — not a demo): https://mso.rahmanef.com
• Watch demo: docs/media/demo.gif

Install

Run one command on the Linux server as your normal user, not root:

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

A fresh install now finishes with a guided terminal onboarding when a controlling terminal is available. curl | bash uses stdin for the downloaded script, so the installer deliberately opens /dev/tty for the prompts instead of silently skipping them. The flow lets you choose:

• Alfa AI provider — OpenAI ChatGPT/Codex device OAuth, or an API-key provider such as Anthropic, OpenAI Platform, OpenRouter, Google, Groq, xAI, DeepSeek or Mistral;
• Alfa response preset — normal, Caveman or Ponytail;
• optional Hermes / OpenClaw / 9Router installation (their provider settings remain separate from Alfa's credentials);
• reviewed installable skills such as Ponytail, Caveman and the MSO-safe RTK wrapper.

The installer also generates the owner login credentials, builds production, installs and starts mso.service, and installs the CLI in both ~/.local/bin/mso and—when the normal service install has sudo available—/usr/local/bin/mso. That system launcher is important: a child curl | bash process cannot modify the PATH of the shell that launched it, so mso -h must work immediately after the installer returns, without asking you to restart the shell. The installer also adds an idempotent ~/.local/bin fallback to the normal shell profile for future sessions.

If the environment has no controlling TTY (CI/cloud-init), the installer never blocks. It prints the resume command instead:

mso onboard

For an intentionally non-interactive install, use safe minimal defaults. -y does not auto-connect external accounts, install large managed apps, or silently add community skills:

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

After installation these should work immediately:

mso -h
mso doctor
mso onboard                 # run/re-run guided setup
mso skills available        # reviewed installable skill list
mso skills install ponytail caveman rtk -y

Caveman/Ponytail appear in two intentionally different places. Response presets (mso config style caveman|ponytail) are lightweight Alfa output policies. The market entries are full SKILL.md packages installed into the trusted operator root ~/.mso/skills. Selecting a preset does not secretly install a skill, and installing a skill does not rewrite the global response preset.

The curated rtk skill is an MSO-safe wrapper: it teaches agents to use RTK when the binary is already present, but it does not run an unpinned remote installer, modify shell profiles, or enable global hooks. Installing the RTK binary is a separate explicit system change.

MSO binds 127.0.0.1 by default, so nothing is published directly to your network. Reach it with an SSH tunnel and open http://localhost:4005:

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

The tunnel is not just hygiene. The session cookie is Secure; ordinary plain-HTTP IP addresses drop it. For a permanent setup use Tailscale Serve or a TLS reverse proxy to 127.0.0.1:4005. Bind wider only when the network/firewall design explicitly requires it.

Useful installer controls:

# force onboarding even while updating an existing install
curl -fsSL https://raw.githubusercontent.com/rahmanef63/mso/main/scripts/install.sh | bash -s -- --onboard

# update/build without onboarding
curl -fsSL https://raw.githubusercontent.com/rahmanef63/mso/main/scripts/install.sh | bash -s -- --no-onboard

# other existing controls
curl -fsSL https://raw.githubusercontent.com/rahmanef63/mso/main/scripts/install.sh | bash -s -- --port 4005
curl -fsSL https://raw.githubusercontent.com/rahmanef63/mso/main/scripts/install.sh | bash -s -- --bind 0.0.0.0
curl -fsSL https://raw.githubusercontent.com/rahmanef63/mso/main/scripts/install.sh | bash -s -- --no-service
curl -fsSL https://raw.githubusercontent.com/rahmanef63/mso/main/scripts/install.sh | bash -s -- --uninstall

There is also a no-login install guide at https://mso.rahmanef.com/install. Full production setup, TLS/VPN notes, filesystem roots, update/rollback and onboarding details live in docs/INSTALL.md.

CLI

The browser UI is one frontend, not the product. The installer puts mso on your PATH, and it reaches the same API — every endpoint has a named verb, and mso api covers anything without one.

mso -h                       # grouped command list; `mso <command> --help` per command
mso doctor                   # deps, env, service, session, device — names what broke
mso onboard                  # guided AI/app/skill setup
mso skills available         # curated installable skills
mso skills install ponytail caveman rtk -y
mso device pending           # who typed the password and is waiting
mso device approve <id> "my phone"
mso ls ~/projects            # files; `raw` for binaries, `zip`/`upload` for transfers
mso exec "df -h"             # host shell
mso stats                    # cpu / mem / disk
mso camoufox start           # power the anti-detection browser
mso mapp logs hermes         # managed apps (hermes, openclaw, 9router)
mso term open                # interactive PTY
mso service restart          # systemd
mso api GET /api/v1/sys/stats   # escape hatch — any endpoint
eval "$(mso completion bash)"   # tab completion

Full command reference: docs/CLI.md (generated from mso --help).

Global options: --base <url> to target another instance, --env <file> to pick a different secrets file. Device and service commands work even while the service is down. If you use Claude Code, the installer also links every committed official skill in claude-skills/ into ~/.claude/skills/. Create a consistent workflow skill with bun run skill:new -- --help and validate the catalog with bun run skill:check.

Security warning

An authenticated MSO session can read allowed files and run commands as the user that owns the process. Treat it like SSH in a browser.

• Run as a dedicated non-root user.
• Prefer Tailscale or a VPN; otherwise use HTTPS plus a strict firewall or allowlist.
• Use a strong OS_SESSION_SECRET and a strong OS_LOGIN_PASSWORD.
• Approve only devices you own; device approval is an allowlist, not standards-based 2FA.
• Keep write roots narrow with OS_FS_WRITE_ROOTS.
• Never commit .env.local, API keys, or data from ~/.mso.
• Managed-app dashboards are not embedded by default. 9Router can use its direct public-IP port without a domain; when a application hostname is configured, that existing domain becomes its primary in-shell UI. Give each vendor UI a separate explicit hostname such as hermes.mso.example.com; there is no supported same-origin iframe mode.
• That boundary is browser-only: a plugin installed into Hermes or OpenClaw runs inside that daemon and can run host commands according to the daemon's own trust model.
• With a model provider configured, Alfa is a tool-calling agent, not a plain chatbot. Its complete current catalog and human-approval contract are generated from frontend/slices/assistant/host-tools/* and documented in frontend/slices/assistant/CONTRACT.md; avoid copying a tool count into overview docs because the catalog changes independently of MCP.
• Everything Alfa reads — file contents, command output, process lists — is sent to your model provider, and is re-sent on every following turn of the same run. BYOK means you own the key, not that the data stays on the box.
• Treat any file Alfa reads as untrusted input. The approval card is the only thing between text hidden inside a file and an exec.run. Read the command on the card, not Alfa's summary of it.
• Agents and Skills group tools for your own convenience. They are not a permission boundary: every agent can call every tool.
• exec.run is not sandboxed. Its cwd is bounded to your write roots, but the command itself runs in your login shell as the service user. The destructive-command denylist is a short accident tripwire, not a guard.
• The MCP server is off unless OS_MCP_ENABLED=1. When on, a bearer token is a standing credential with whatever scope you granted it: at exec it runs any command on the box as you, and every call and result goes to the client's provider. The consent screen preselects the server ceiling (exec by default), so lower it before Allow when a client needs less; cap all tokens with OS_MCP_MAX_SCOPE, and treat anything the model reads as untrusted — scope is what stops a prompt-injected file talking it into a write. See docs/MCP.md.
• MSO has not had a third-party security audit.

More detail: SECURITY.md, docs/FAQ.md and docs/INSTALL.md.

How it works

MSO is a single Next.js app that runs on your server as one non-root Node process. The app talks to host capabilities through local server routes and keeps features as vertical slices under frontend/slices/<slug>/.

flowchart LR
  U["Phone / Browser"]
  subgraph VPS["Your Linux server"]
    APP["MSO / mso<br/>Next.js 16 · React 19"]
    HOST["Host layer<br/>fs · PTY · sys metrics"]
    SLICES["Feature slices<br/>Files · Terminal · Monitor · Assistant"]
    AI["Alfa AI<br/>BYOK"]
    MANAGED["Managed apps<br/>Hermes · OpenClaw · 9Router<br/>own runtime + data"]
  end
  U -->|"HTTPS or Tailscale/VPN"| APP
  U -->|"framed dashboard, per-app origin<br/>same process, different origin"| APP
  APP --> HOST
  APP --> SLICES
  APP --> AI
  APP -->|"their CLI · loopback HTTP · systemd"| MANAGED

Loading

Deep dive: docs/ARCHITECTURE.md.

Comparison

The tools below have different scopes. This comparison is intended to explain where MSO fits, not to claim it replaces every specialized server administration tool.

	MSO	Cockpit	ttyd	FileBrowser	Netdata	Tailscale SSH
Product maturity	Early alpha	Mature	Varies	Mature	Mature	Mature
Third-party security audit	No	Varies	Varies	Varies	Varies	Yes
Multi-user support	No	Yes	Varies	Yes	Yes	Yes
Mobile-first interface	Yes	Partial	Varies	Partial	Partial	Not a focus
Real PTY	Yes	Yes	Yes	No	No	Yes
File manager	Yes	Partial	No	Yes	No	No
Metrics	Yes	Yes	No	No	Yes	No
Built-in AI	Yes, BYOK	No	No	No	No	No
Setup complexity	One script	Varies	Low	Low	Varies	Low
Service/package administration	Basic	Strong	Not a focus	Not a focus	Metrics focus	SSH only

Development

bun install
cp .env.example .env.local
bun run dev

Quality gates:

bun run verify              # typecheck + lint + test + checks + audit
node scripts/check-docs.mjs   # docs links/toolset/slice drift
bash scripts/verify-build.sh   # build HEAD out-of-tree — safe on the prod checkout
bash -n scripts/install.sh

The package manager is bun (bun.lock is committed); the runtime stays Node 22 — next, tsc, eslint and vitest all carry a #!/usr/bin/env node shebang and bun honours it, and production runs npm run start. Use bun so the lockfile and the native node-pty build path stay predictable: node-pty has no Linux prebuild and is listed under trustedDependencies, without which its postinstall is skipped and the whole /api/v1 surface fails to load.

Full guide: docs/DEVELOPMENT.md.

Tested platforms

Not yet formally tested across a full distro matrix.

Tested:

• Ubuntu 22.04
• Ubuntu 24.04

Expected to work:

• Debian 12
• Other systemd-based Linux distributions with Node.js 20.9+ and build tools

Not currently supported:

• Windows host
• macOS host
• Automatic service install on non-systemd hosts
• Root deployment

Documentation

Doc	What's in it
docs/README.md	Documentation map: current reference vs generated vs historical
docs/INSTALL.md	Server install, credentials, TLS/VPN, update/rebuild, persistence
docs/CLI.md	Generated mso command-line reference
docs/DEVELOPMENT.md	Local dev, gates and exact release flow
docs/ARCHITECTURE.md	Current AppShell/host/MCP/managed-app architecture
docs/MANAGED-APPS.md	Hermes/OpenClaw/9Router lifecycle, jobs, update, backup/restore and origins
docs/HERMES-INTEGRATION.md	Hermes-specific managed-app behaviour
docs/OPENCLAW-INTEGRATION.md	OpenClaw-specific managed-app behaviour
docs/9ROUTER-INTEGRATION.md	9Router server ownership, existing-domain-first in-shell UI and public-IP fallback
docs/MODELS-INTEGRATION.md	Alfa BYOK/custom/Codex model credentials
docs/MCP.md	MCP/OAuth tools, discovery, workflow memory and security internals
docs/CHATGPT-PLUGIN.md	ChatGPT custom MCP app setup + architecture/OAuth/tool/file diagrams
docs/FAQ.md	Security, product and operator boundaries
docs/TROUBLESHOOTING.md	Current symptom → cause → supported recovery
SECURITY.md	Security posture and vulnerability reporting

Status

MSO is Public Alpha / Developer Preview. The core auth, filesystem bounds, terminal, metrics, and slice architecture are implemented, but the project is still early and unaudited. Expect rough edges, breaking changes, and missing production hardening.

License

MIT — see LICENSE.