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.
Managed applications
Current reference. MSO currently manages three independent applications: Hermes, OpenClaw, and 9Router.
Managed applications are separate runtimes with their own install, config, data and privileges. MSO does not turn them into MSO slices. It provides a management layer around their existing CLI/systemd/Docker/dashboard interfaces.
flowchart LR
U[MSO owner] --> M[Managed Apps UI]
M --> API[/api/v1/managed-apps/*]
API --> C[lib/managed-apps]
C --> S[systemd / Docker / CLI probes]
C --> J[persisted job runner]
C --> B[backup + restore]
C --> P[optional dashboard proxy]
S --> H[Hermes]
S --> O[OpenClaw]
S --> N[9Router]
J --> H
J --> O
J --> N
P --> H
P --> O
P --> N
Live proxy authority
Production starts through node scripts/server.mjs (also used by bun start and the
gateway runtime). The public Node server owns WebSocket upgrades and forwards normal
HTTP to Next on a private loopback socket. Its private, process-secret policy endpoint
reuses the same live device/session checks as HTTP. Managed dashboards and Camoufox
revalidate before both socket directions deliver data and every second while idle.
Logout, device revocation/demotion, expiry or session-policy rotation closes access.
The process caps active proxy sockets at 32 and refuses redirects/off-loopback targets.
The stock development server refuses these upgrades; use the production entry point
for authenticated dashboard/viewer sockets. Terminal event streams similarly recheck
owner authority before delivery and while idle, closing their PTY on authority loss.
Managed-app health probes refuse redirects rather than follow them away from loopback.
1. Current application model
| App | MSO-managed runtime | Internal dashboard upstream | Direct browser access | State directory |
|---|---|---|---|---|
| Hermes | user systemd (hermes-dashboard.service, hermes-gateway.service) or pinned Docker fallback |
127.0.0.1:9119 by default |
none by default | ~/.hermes or HERMES_HOME |
| OpenClaw | user systemd (openclaw-gateway.service) |
127.0.0.1:18789 by default |
none by default | ~/.openclaw |
| 9Router | Docker container 9router |
127.0.0.1:20128 by default |
none by default; public-IP access requires explicit NINE_ROUTER_EXPOSE_PUBLIC=1 |
~/.9router mounted at /app/data |
Detection reads systemd first, then Docker/package evidence. If MSO cannot reach the user systemd bus, it reports that uncertainty instead of silently treating a running app as "not installed". Install and restore fail closed when required state cannot be proven.
9Router upstream publishes both an npm CLI and Docker images. MSO deliberately manages
the Docker distribution on servers/VPSes; this matches upstream's server/VPS quick start and
avoids starting a second 9Router process on the same port. Docker may need to be started manually
on hosts without systemd; MSO does not widen 9Router just to compensate. The repo-owned
scripts/managed-app-9router is an MSO lifecycle/update adapter, not the upstream CLI. Install with
scripts/managed-app-9router install or mso mapp install 9router; the safe bind remains
127.0.0.1:20128 unless the owner explicitly opts into NINE_ROUTER_EXPOSE_PUBLIC=1.
OpenClaw needs a working user systemd bus. Hermes uses user systemd when available and can
fall back to its reviewed Docker runtime if the daemon is accessible to the MSO service user.
9Router needs an accessible Docker daemon. On a Termux/PRoot host without either backend, MSO
rejects all three install jobs before downloads; the tablet can still host the MSO core.
A Linux guest on Windows/macOS follows the same backend checks inside that guest. Ensure linger,
XDG_RUNTIME_DIR, and the user manager are healthy for apps using user systemd; do not treat
a partially available bus as a successful half-install.
2. User experience
Opening a managed app first detects it:
- not installed → one-click Install surface;
- installed but stopped → Start surface;
- running/starting/unhealthy → the app surface;
- Details → MSO-owned lifecycle, logs, update, backup/restore and uninstall controls.
The app surface can switch between UI and CLI where a UI is available. Hermes and
OpenClaw use their safe split-origin embedded dashboard when configured. 9Router follows the
same rule: a configured application domain is the primary in-shell UI. Its Docker runtime
publishes port 20128 on loopback by default. Only an explicit public-exposure choice allows
MSO to advertise a direct separate-origin URL and open it in a dedicated browser tab.
When no domain is configured, MSO intentionally does not iframe http://<public-ip>:20128 inside an HTTPS cockpit: browsers
block that as mixed content. It also does not proxy a vendor SPA under the cockpit origin,
because a same-origin SPA with allow-same-origin could reach the owner's MSO session/API.
For 9Router's CLI view MSO starts with docker logs --tail 80 9router, then leaves the shell
interactive. It does not auto-run 9router (which starts another server) and does not use
the nonexistent 9router status command.
3. Lifecycle versus jobs
Short lifecycle actions are bounded synchronous operations:
startstoprestartbackup
Install, update, uninstall and restore can outlive one HTTP request. They run as persisted
managed-app jobs with states queued, running, succeeded, failed or interrupted, a
bounded transcript, heartbeat/liveness data and app ownership. Closing the MSO window does
not cancel a running job.
The public managed-app API is:
| Route | Purpose |
|---|---|
GET /api/v1/managed-apps |
detect/list Hermes, OpenClaw and 9Router |
GET /api/v1/managed-apps/[id] |
detect/read one managed app |
POST /api/v1/managed-apps/[id] |
start/stop/restart/backup |
GET /api/v1/managed-apps/[id]/logs |
recent logs |
GET /api/v1/managed-apps/[id]/backups |
snapshot list |
POST /api/v1/managed-apps/[id]/install |
start install job |
GET/POST /api/v1/managed-apps/[id]/update |
update status and actions |
GET /api/v1/managed-apps/[id]/jobs |
job history/current work |
GET/DELETE /api/v1/managed-apps/[id]/jobs/[jobId] |
job status/cancel where supported |
/api/v1/managed-apps/[id]/proxy/* |
authenticated optional vendor-dashboard reverse proxy |
There is intentionally no /features endpoint.
4. Install
MSO installs all three apps non-interactively through scripts/managed-app-install and the
same persisted job layer used for updates.
- Hermes verifies the SHA-256 of a pinned release installer and forces the checkout to the reviewed upstream commit before setup.
- OpenClaw verifies the SHA-512 of an exact npm tarball before lifecycle scripts can run.
- 9Router delegates to
scripts/managed-app-9router, pulls and verifies the reviewed multi-architecture digest, creates~/.9router, and runs the container with--restart unless-stopped,-p 127.0.0.1:20128:20128, and~/.9router:/app/data.
A domain is not an install prerequisite for lifecycle management. 9Router's dashboard is
loopback-only after install unless a configured URL/split-origin host exists or the operator
explicitly sets NINE_ROUTER_EXPOSE_PUBLIC=1. Domain-provider integrations
(Cloudflare initially) are optional. After a successful install/update job, and after
start/restart actions, saved automatic domain settings trigger reconciliation. DNS failures
are reported separately from application success. See MANAGED-DOMAINS.md
for one-time setup, mso mapp enable 9router, status and recovery.
An optional model-provider API key can be supplied to app installers that support it. Keys are passed through the child environment rather than persisted job argv/transcripts.
5. Update centre
Every real update takes an MSO state snapshot first. If that snapshot fails, the update is abandoned before invoking the upstream updater.
Hermes
- supports check + apply;
- upstream has no true update dry-run; its read-only check is the preview;
- branch switching exists upstream but is not presented as an ordinary channel menu.
OpenClaw
- supports check + apply + real
--dry-run; - supports channels/tags and exact-version pinning within MSO's allowlist;
- normal update restarts and verifies the app rather than leaving new bytes behind an old process.
9Router
/api/versionsupplies current/latest/update-available state;- apply pulls the configured Docker image and recreates the
9routercontainer; - the
~/.9routerdata mount is preserved across recreation; - upstream's
latestimage is the managed channel, so MSO does not expose a fake channel or version-pin control that upstream does not provide in this install mode.
Update commands use argv arrays, not shell interpolation. User-supplied values pass explicit validation first.
6. Backups
Snapshots live under:
~/.mso/backups/<app>/<timestamp>/
They may contain credentials and should be protected like the app's original state. The
snapshot directory is private and its manifest is 0600.
Stop every app service before taking a snapshot, updating or restoring. MSO checks all catalog units in both systemd scopes and all discovered containers under the operation lease; an external restart detected during the copy aborts it and removes the incomplete snapshot. A restore reports its safety snapshot if copying had already begun.
Snapshots skip symlinks and recursively exclude reinstallable/cache trees such as
node_modules, .venv, venv, __pycache__, .git, .cache, and nested backups.
The manifest records the app, original source path, reason, file/byte counts and exclusions.
For 9Router the important persistent state is ~/.9router; the container itself is
reinstallable and is not the backup target.
7. Restore
Restore is intentionally conservative.
- MSO must prove the app is stopped; an uncertain systemd reading is a refusal.
- Backup id and manifest must identify this app and its current state directory.
- Target state directory must be a real safe directory, not a symlink or home ancestor.
- MSO checks the snapshot/target trees for symlink collisions before writing.
- MSO first creates a
pre-restoresafety snapshot of current state. - Snapshot files overwrite matching files.
- Files created after the snapshot are not deleted.
- Excluded reinstallable/cache directories were never in the snapshot and are not restored.
Restore is therefore an overwrite restore, not a byte-for-byte directory replacement.
8. Uninstall
MSO takes a backup first and uses conservative removal scopes.
- Hermes removal keeps its state/config by default.
- OpenClaw removal targets its gateway service + local state within the supported scope.
- 9Router removal stops/removes only the
9routercontainer. The image and~/.9routerstate stay, so reinstalling can return with existing providers/keys/stats.
The UI can preview removal when the adapter proves dry-run support, and server-side confirmation is still required for a real removal.
9. Browser access and dashboard origin boundary
Lifecycle does not require a domain. These are separate concerns:
- Runtime management — install/start/stop/update/backup/uninstall; no DNS required.
- Direct public access — an explicit 9Router exception only when no embeddable domain is
configured and
NINE_ROUTER_EXPOSE_PUBLIC=1; only then is port20128published beyond loopback and MSO may derive a routable address forpublicDashboardUrl. The normal install is loopback-only and has no direct-address fallback. - Embedded dashboard access — preferred when configured: split-origin mode for a vendor UI shown inside MSO.
The safe embedded-dashboard default is off. To opt in, configure all parts of one split-origin decision:
NEXT_PUBLIC_MANAGED_APP_HOST_TEMPLATE={id}.mso.example.com
OS_PUBLIC_ORIGIN=https://mso.example.com
Then provision DNS/TLS only for managed-app hostnames you actually use (for the current
catalog: hermes, openclaw, and optionally 9router). Each hostname is rewritten
exclusively into that app's proxy; cockpit pages/API/static chunks are not served there.
mso domain setup persists these settings and activates automatic provisioning after the
required deployment. App-bound tickets exchange for host-only app cookies;
OS_SESSION_COOKIE_DOMAIN is obsolete and must not be widened for this flow.
flowchart LR
TOP[https://mso.example.com] -->|optional iframe| HH[https://hermes.mso.example.com]
TOP -->|optional iframe| OH[https://openclaw.mso.example.com]
TOP -->|optional iframe| NH[https://9router.mso.example.com]
HH -->|MSO proxy| H[Hermes loopback]
OH -->|MSO proxy| O[OpenClaw loopback]
NH -->|MSO proxy| N[9Router loopback]
N -. no DNS required .-> PI[http://public-ip:20128]
Why the split exists: vendor SPAs need allow-same-origin to work. If their JavaScript
shared the cockpit origin, it would share the owner's browser realm/session. A separate
hostname makes window.top cross-origin. There is no supported same-origin dashboard
fallback.
Provision only explicit names you intend to serve. Unknown app namespace hosts are refused. The cockpit session stays host-only; app authorization rechecks live device authority.
10. 9Router distribution and ownership
Upstream's npm package remains a valid desktop/local way to run 9Router:
npm install -g 9router
9router
That is not the runtime MSO owns on a VPS. Running the npm launcher beside the Docker
container can contend for port 20128, and sharing ~/.9router between root-written Docker
runtime artifacts and an npm updater can also create ownership problems. MSO therefore keeps
one authority: Docker for the server runtime, with the repo-owned adapter for lifecycle.
See 9ROUTER-INTEGRATION.md for the app-specific contract.
11. Project ingress is separate
OS_PROJECT_INGRESS_ROUTES is not part of managed-app dashboard management. It is a generic
opt-in seam for exact project-owned POST callbacks. It defaults empty, targets loopback
services only, and applies an HMAC-shaped request prefilter. The target project still owns
the real secret verification.
12. Troubleshooting quick map
- app says "not installed" but you know it exists → check systemd-user visibility/detection evidence before rerunning an installer;
- 9Router is healthy but its configured app host fails → run
mso domain doctor 9router; inspect DNS, tunnel, app-host activation and HTTPS separately; - 9Router UI button has no public URL →
NINE_ROUTER_EXPOSE_PUBLICis unset/false (the safe default), or the explicitly exposed host has no routable address on a local interface; - dashboard frame missing but service is healthy → split-origin embedding may be absent by design; Details and direct access (where defined) still work;
- update refused → inspect the pre-update backup error first;
- restore refused → stop the app and resolve state-path/symlink diagnostics;
- long update appears to vanish → reopen Details; job state/transcript is server-side.