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.
TypeScript browser-shellcontrol-planefile-managerhomelabmobile-firstnextjsptyreactself-hostedserver-managementshadcn-uisysadmintailwindcssterminaltypescriptvpsweb-desktopweb-terminal
fix(managed-apps): make 9router public-ip first
Rahman8f5597562f1d
diff --git a/.env.example b/.env.exampleindex c77da60f..b03b481d 100644--- a/.env.example+++ b/.env.example@@ -92,10 +92,11 @@ OS_SESSION_SECRET=# closed, on purpose, rather than naming a guessed origin as a permitted framer.# OS_PUBLIC_ORIGIN=https://mso.example.com-# --- Managed-app dashboards: ONE decision, TWO variables ----# Unset (default) = MSO does not serve the Hermes/OpenClaw vendor web UI. Their-# MSO Details management surface (install/start/log/update/backup/restore) remains-# available; only the embedded vendor dashboard is absent.+# --- Embedded managed-app dashboards: optional split-origin decision ---+# Unset (default) = MSO does not EMBED vendor web UIs. Managed-app lifecycle and+# Details still work without a domain. 9Router's Docker/VPS install can additionally+# advertise http://<public-ip>:20128 directly; that public-IP path does not depend on+# any variables in this section.## There is no fallback to serving them under a path on the cockpit's origin. That# mode existed and was removed: those SPAs need allow-same-origin to run at all,@@ -107,8 +108,9 @@ OS_SESSION_SECRET=# process, cross-origin — so `window.top` is opaque:## 1. NEXT_PUBLIC_MANAGED_APP_HOST_TEMPLATE — `{id}` is the app id, so this-# yields hermes.mso.example.com and openclaw.mso.example.com. Each host-# needs its own DNS record + TLS pointing at this app. On such a host the+# yields hermes.mso.example.com, openclaw.mso.example.com, 9router.mso.example.com,+# etc. Provision ONLY the explicit app hosts you actually embed; each needs its+# own DNS record + TLS pointing at this app. On such a host the# middleware rewrites EVERY path into that app's proxy and 404s the rest, so# the cockpit API does not exist there.# 2. OS_SESSION_COOKIE_DOMAIN — the session cookie is host-only by default anddiff --git a/README.md b/README.mdindex 880efdd9..1862f161 100644--- a/README.md+++ b/README.md@@ -53,7 +53,7 @@ For a real deployment, put MSO behind **Tailscale, a VPN, or a TLS reverse proxy- **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), driven through their own CLIs and systemd units. Each app's own dashboard opens in a window; give each one its own hostname and it is served from its own origin (opt-in, two env vars). See [docs/MANAGED-APPS.md](./docs/MANAGED-APPS.md).+- **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 works public-IP-first without a domain; embedded vendor dashboards use explicit separate origins only when configured. See [docs/MANAGED-APPS.md](./docs/MANAGED-APPS.md).**Work** — code/text editor, browser, and media tools in the same workspace.@@ -108,7 +108,7 @@ The flow lets you choose:- **Alfa AI provider** — OpenAI ChatGPT/Codex device OAuth, or an API-key provider suchas Anthropic, OpenAI Platform, OpenRouter, Google, Groq, xAI, DeepSeek or Mistral;- **Alfa response preset** — normal, Caveman or Ponytail;-- optional **Hermes / OpenClaw** installation (their provider settings remain separate+- optional **Hermes / OpenClaw / 9Router** installation (their provider settings remain separatefrom Alfa's credentials);- reviewed **installable skills** such as Ponytail, Caveman and the MSO-safe RTK wrapper.@@ -205,7 +205,7 @@ mso ls ~/projects # files; `raw` for binaries, `zip`/`upload` for tramso exec "df -h" # host shellmso stats # cpu / mem / diskmso camoufox start # power the anti-detection browser-mso mapp logs hermes # managed apps (hermes, openclaw)+mso mapp logs hermes # managed apps (hermes, openclaw, 9router)mso term open # interactive PTYmso service restart # systemdmso api GET /api/v1/sys/stats # escape hatch — any endpoint@@ -229,7 +229,7 @@ An authenticated MSO session can read allowed files and run commands as the user- 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. If enabled, give Hermes/OpenClaw separate explicit hostnames such as `hermes.mso.example.com`; there is no supported same-origin iframe mode.+- Managed-app dashboards are not embedded by default. 9Router can use its direct public-IP port without a domain. If embedding is enabled, 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.@@ -253,7 +253,7 @@ flowchart LRHOST["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<br/>own runtime + data"]+ MANAGED["Managed apps<br/>Hermes · OpenClaw · 9Router<br/>own runtime + data"]endU -->|"HTTPS or Tailscale/VPN"| APPU -->|"framed dashboard, per-app origin<br/>same process, different origin"| APP@@ -333,9 +333,10 @@ Not currently supported:| [docs/CLI.md](./docs/CLI.md) | Generated `mso` command-line reference || [docs/DEVELOPMENT.md](./docs/DEVELOPMENT.md) | Local dev, gates and exact release flow || [docs/ARCHITECTURE.md](./docs/ARCHITECTURE.md) | Current AppShell/host/MCP/managed-app architecture |-| [docs/MANAGED-APPS.md](./docs/MANAGED-APPS.md) | Hermes/OpenClaw lifecycle, jobs, update, backup/restore and origins |+| [docs/MANAGED-APPS.md](./docs/MANAGED-APPS.md) | Hermes/OpenClaw/9Router lifecycle, jobs, update, backup/restore and origins || [docs/HERMES-INTEGRATION.md](./docs/HERMES-INTEGRATION.md) | Hermes-specific managed-app behaviour || [docs/OPENCLAW-INTEGRATION.md](./docs/OPENCLAW-INTEGRATION.md) | OpenClaw-specific managed-app behaviour |+| [docs/9ROUTER-INTEGRATION.md](./docs/9ROUTER-INTEGRATION.md) | 9Router server ownership, public-IP-first UI and optional domain embedding || [docs/MODELS-INTEGRATION.md](./docs/MODELS-INTEGRATION.md) | Alfa BYOK/custom/Codex model credentials || [docs/MCP.md](./docs/MCP.md) | MCP/OAuth tools, discovery, workflow memory and security internals || [docs/CHATGPT-PLUGIN.md](./docs/CHATGPT-PLUGIN.md) | ChatGPT custom MCP app setup + architecture/OAuth/tool/file diagrams |diff --git a/docs/9ROUTER-INTEGRATION.md b/docs/9ROUTER-INTEGRATION.mdnew file mode 100644index 00000000..3b499767--- /dev/null+++ b/docs/9ROUTER-INTEGRATION.md@@ -0,0 +1,127 @@+# 9Router integration++9Router is a managed application in MSO. This document defines the server/VPS contract so+future changes do not confuse its upstream npm CLI, Docker runtime, public access, and+optional MSO dashboard proxy.++## Distribution choice++Upstream publishes both:++- npm CLI: `npm install -g 9router` then `9router`;+- Docker: `decolua/9router:latest` with port `20128` and persistent `/app/data`.++MSO uses **Docker for the managed server runtime**. The upstream README recommends Docker for+server/VPS use, and one owner avoids running two 9Router servers against the same port/data.+`scripts/managed-app-9router` is MSO's adapter for install/update/status/uninstall; it is not+evidence that upstream lacks a CLI.++## Runtime contract++Default container:++```text+name: 9router+image: decolua/9router:latest+restart: unless-stopped+host port: 20128 -> container 20128+state: ~/.9router -> /app/data+DATA_DIR: /app/data+health: GET http://127.0.0.1:20128/api/health+version/update check: GET http://127.0.0.1:20128/api/version+```++MSO uses loopback for trusted internal health/version calls even though Docker publishes the+port publicly.++## Public-IP-first UI++A 9Router installation must not depend on a domain. When MSO sees a globally-routable IPv4+on the host, its managed-app view advertises:++```text+http://<public-ip>:20128+```++The MSO 9Router window offers **UI / CLI**. UI opens that direct URL in a dedicated tab. It+is intentionally not put in an HTTPS iframe because browsers block HTTP mixed content.+Because the direct URL is a different origin, vendor JavaScript also cannot inherit the MSO+cockpit origin/session.++A custom domain is optional. Hostinger/Cloudflare automation may later configure DNS/TLS,+but it is not part of install health and must never be assumed to exist.++## Optional split-origin embedding++If an operator wants 9Router embedded inside an HTTPS MSO window, use the same explicit+split-origin contract as other vendor dashboards:++```dotenv+NEXT_PUBLIC_MANAGED_APP_HOST_TEMPLATE={id}.mso.example.com+OS_SESSION_COOKIE_DOMAIN=.mso.example.com+OS_PUBLIC_ORIGIN=https://mso.example.com+```++Then create only the explicit `9router.mso.example.com` DNS/TLS route and re-authenticate so+the widened session cookie is actually issued. This path is optional; a failing split-origin+hostname must not make the running 9Router app appear unavailable.++An older standalone hostname such as `9-router.example.com` may continue proxying directly+to port 20128. MSO does not need to delete or replace it when enabling managed-app support.++## CLI view++Do not auto-run any of these in the MSO terminal:++```text+9router # starts a server+9router status # not an upstream command+```++For the MSO-owned Docker runtime the safe opening command is:++```bash+docker logs --tail 80 9router+```++The terminal remains interactive afterwards. The upstream npm CLI can still be used+manually for its documented subcommands when an operator intentionally installed it, but it+is not MSO's server lifecycle authority.++## Lifecycle++- **Install**: pull image, create data directory, run container, wait for `/api/health`.+- **Start/stop/restart**: Docker lifecycle against the detected `9router` container.+- **Update check**: app `/api/version` response.+- **Update**: pre-update MSO state backup, pull image, recreate container, preserve data+ mount, wait for health.+- **Uninstall preview**: reports the container that would be removed and state/image kept.+- **Uninstall**: remove the container only. `~/.9router` and image remain.+- **Restore**: uses the normal managed-app state snapshot rules while the app is stopped.++## Verification++On a server where 9Router is installed:++```bash+./scripts/managed-app-9router --version+./scripts/managed-app-9router check --json+./scripts/managed-app-9router status+./scripts/managed-app-9router uninstall --yes --dry-run+curl -fsS http://127.0.0.1:20128/api/health+```++For a public-IP installation also confirm the public address responds from the intended+network. A local curl to the public address proves binding/routing on the host but does not+prove an upstream cloud firewall permits arbitrary external clients.++## Failure map++- **Old standalone domain works, new `9router.mso...` does not**: 9Router itself is likely+ fine. Check direct public-IP access first. The new name is an MSO split-origin concern+ (DNS/TLS + cookie domain + re-login), not an application-health dependency.+- **`401` only on the split-origin host**: verify the MSO session cookie was re-issued with+ the configured cookie domain; a curl without an authenticated cookie will also get 401.+- **`/health` says 404**: expected endpoint is `/api/health`.+- **npm update fails with ownership errors after Docker use**: do not mix npm-owned runtime+ updates with the Docker-managed `~/.9router` server state. Keep Docker as the VPS owner.diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.mdindex c35173ec..7917c518 100644--- a/docs/ARCHITECTURE.md+++ b/docs/ARCHITECTURE.md@@ -55,7 +55,7 @@ frontend/slices/ vertical application sliceslib/auth/ login/session/device approvallib/host/ bounded host capability implementationlib/mcp/ OAuth/MCP tool catalog and dispatcher-lib/managed-apps/ Hermes/OpenClaw lifecycle/update/backup/proxy+lib/managed-apps/ Hermes/OpenClaw/9Router lifecycle/update/backup/proxylib/skills/ trusted skill discovery and semantic searchscripts/ install, release, checks and service helpersclaude-skills/ official trusted operational playbooks@@ -112,7 +112,7 @@ through the app catch-all.- `term/*` — interactive PTY lifecycle and streaming- `sys/*` — stats, processes, cleanup, audit and self-update- `camoufox/*` — browser service/session control-- `managed-apps/*` — Hermes/OpenClaw lifecycle, jobs, backups and proxying+- `managed-apps/*` — Hermes/OpenClaw/9Router lifecycle, jobs, backups and optional proxying`OS_FS_READ_ROOTS` and `OS_FS_WRITE_ROOTS` constrain filesystem access. The implementationuses canonical path/containment checks and additionally blocks credential material such as@@ -161,22 +161,26 @@ fed directly to the model. See `skills/README.md`.## 8. Managed applications-Hermes and OpenClaw are managed, not embedded into MSO's process model. MSO can detect,-install, start/stop/restart, read logs, update, back up, restore and conservatively uninstall-them. Long-running install/update/uninstall/restore work is represented as jobs with bounded-logs and status.+Hermes, OpenClaw and 9Router are managed, not embedded into MSO's process model. MSO can+detect, install, start/stop/restart, read logs, update, back up, restore and conservatively+uninstall them. Long-running install/update/uninstall/restore work is represented as jobs+with bounded logs and status.-Their vendor dashboards are optional. The safe default is no embedded dashboard. A-split-origin deployment opts in by setting both `NEXT_PUBLIC_MANAGED_APP_HOST_TEMPLATE` and-`OS_SESSION_COOKIE_DOMAIN`, giving each dashboard its own hostname while the same MSO-process proxies its loopback upstream. There is no supported same-origin dashboard mode.+A domain is not a lifecycle dependency. 9Router's Docker/server form deliberately publishes+port 20128; when the host has a global IPv4 MSO advertises `http://<public-ip>:20128` as a+direct separate-origin UI. Hermes/OpenClaw stay loopback-only by default.-There is also no runtime navigation/feature scraping of Hermes/OpenClaw bundles. The old+Embedded vendor dashboards are optional. A split-origin deployment opts in by setting+`NEXT_PUBLIC_MANAGED_APP_HOST_TEMPLATE` and `OS_SESSION_COOKIE_DOMAIN`, giving each embedded+dashboard its own hostname while the same MSO process proxies its loopback upstream. There+is no supported same-origin dashboard mode.++There is also no runtime navigation/feature scraping of managed-app bundles. The old`/features` route and parser pipeline were removed; current MSO presents the vendor's owndashboard as one surface plus MSO's Details management surface.-See `docs/MANAGED-APPS.md`, `docs/HERMES-INTEGRATION.md` and-`docs/OPENCLAW-INTEGRATION.md`.+See `docs/MANAGED-APPS.md`, `docs/HERMES-INTEGRATION.md`,+`docs/OPENCLAW-INTEGRATION.md` and `docs/9ROUTER-INTEGRATION.md`.## 9. Camoufox Browserdiff --git a/docs/CHANGELOG.md b/docs/CHANGELOG.mdindex 61396cfd..ac38748d 100644--- a/docs/CHANGELOG.md+++ b/docs/CHANGELOG.md@@ -12,6 +12,7 @@ this is the *what*, and it is what Settings → About shows as “What's new”.**Fixed**+- `managed-apps` make 9router public-ip first- harden security state and credential guards## 2026-08-23diff --git a/docs/INSTALL.md b/docs/INSTALL.mdindex e5145f63..4195c590 100644--- a/docs/INSTALL.md+++ b/docs/INSTALL.md@@ -238,10 +238,13 @@ ChatGPT app; MSO's "Mark ChatGPT refreshed" button is only a local acknowledgeme## 10. Optional managed-app dashboards-Hermes/OpenClaw lifecycle management works without embedding their web dashboards. The safe-default is therefore no vendor dashboard on the MSO origin.+Hermes, OpenClaw and 9Router lifecycle management works without a domain. 9Router is+public-IP-first on the managed Docker/VPS path: after health succeeds, its UI can be opened+at `http://<public-ip>:20128` when the host has a globally-routable IPv4. Hermes/OpenClaw+remain loopback-only unless an operator adds an external route.-To opt into split-origin embedding, configure **both**:+The safe default is no vendor dashboard on the **MSO cockpit origin**. To opt into+split-origin embedding, configure:```dotenvNEXT_PUBLIC_MANAGED_APP_HOST_TEMPLATE={id}.mso.example.com@@ -249,9 +252,10 @@ OS_SESSION_COOKIE_DOMAIN=.mso.example.comOS_PUBLIC_ORIGIN=https://mso.example.com```-Provision DNS/TLS only for the explicit `hermes` and `openclaw` hostnames and sign out/in-after changing the cookie domain. There is no supported same-origin iframe fallback. See-`docs/MANAGED-APPS.md`.+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 modediff --git a/docs/MANAGED-APPS.md b/docs/MANAGED-APPS.mdindex bfed1542..58f078d5 100644--- a/docs/MANAGED-APPS.md+++ b/docs/MANAGED-APPS.md@@ -1,12 +1,11 @@# Managed applications-> **Current reference.** MSO currently manages exactly two independent applications:-> **Hermes** and **OpenClaw**. Older workspace-mode and dynamic upstream-feature-discovery-> designs are historical; there is no `/features` route in the current API.+> **Current reference.** MSO currently manages three independent applications:+> **Hermes**, **OpenClaw**, and **9Router**.-Managed applications are separate daemons with their own install, config, data and+Managed applications are separate runtimes with their own install, config, data andprivileges. MSO does not turn them into MSO slices. It provides a management layer around-their existing CLI/systemd/dashboard interfaces.+their existing CLI/systemd/Docker/dashboard interfaces.```mermaidflowchart LR@@ -14,39 +13,59 @@ flowchart LRM --> API[/api/v1/managed-apps/*]API --> C[lib/managed-apps]C --> S[systemd / Docker / CLI probes]- C --> J[long-running job runner]+ C --> J[persisted job runner]C --> B[backup + restore]- C --> P[dashboard proxy]+ C --> P[optional dashboard proxy]S --> H[Hermes]S --> O[OpenClaw]+ S --> N[9Router]J --> HJ --> O+ J --> NP --> HP --> O+ P --> N```## 1. Current application model-| App | Primary service(s) | Dashboard upstream | State directory |-|---|---|---|---|-| Hermes | `hermes-dashboard.service`, `hermes-gateway.service` | `127.0.0.1:9119` by default | `~/.hermes` or `HERMES_HOME` |-| OpenClaw | `openclaw-gateway.service` | `127.0.0.1:18789` by default | `~/.openclaw` |+| App | MSO-managed runtime | Internal dashboard upstream | Direct browser access | State directory |+|---|---|---|---|---|+| Hermes | user systemd (`hermes-dashboard.service`, `hermes-gateway.service`) | `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 | `http://<public-ip>:20128` when the host has a global IPv4 | `~/.9router` mounted at `/app/data` |Detection reads systemd first, then Docker/package evidence. If MSO cannot reach the usersystemd bus, it reports that uncertainty instead of silently treating a running app as-"not installed". Install and restore fail closed when the required state cannot be proven.+"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. The repo-owned+`scripts/managed-app-9router` is an MSO lifecycle/update adapter, not the upstream CLI.## 2. User experience-Opening Hermes/OpenClaw first detects the app:+Opening a managed app first detects it:-- **not installed** → Install surface;+- **not installed** → one-click Install surface;- **installed but stopped** → Start surface;-- **running/starting/unhealthy with a reachable dashboard** → vendor dashboard surface;-- **Details** → MSO-owned management surface regardless of vendor UI.+- **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 is+**public-IP-first**: its Docker runtime publishes port `20128`, so MSO advertises the direct+separate-origin URL and opens it in a dedicated browser tab. This requires no domain, DNS+provider, wildcard record, or TLS configuration.-The Details surface exposes lifecycle state, version, health, logs, update centre and-backups. It does not scrape the vendor's internal navigation into MSO launcher items.+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@@ -58,15 +77,15 @@ Short lifecycle actions are bounded synchronous operations:- `backup`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.+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 and OpenClaw |+| `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 |@@ -75,20 +94,27 @@ The public managed-app API is:| `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 vendor-dashboard reverse proxy |+| `/api/v1/managed-apps/[id]/proxy/*` | authenticated optional vendor-dashboard reverse proxy |There is intentionally no `/features` endpoint.## 4. Install-MSO can install both apps non-interactively through `scripts/managed-app-install` and the-same job layer used for updates. An optional model-provider API key can be supplied during-install. The key is accepted in the request body, passed to the child through its-environment and immediately dropped from React state; it is not put in argv, job records or-MSO's audit transcript.+MSO installs all three apps non-interactively through `scripts/managed-app-install` and the+same persisted job layer used for updates.++- **Hermes/OpenClaw** use their upstream installers and user-systemd lifecycle.+- **9Router** delegates to `scripts/managed-app-9router`, pulls `decolua/9router:latest`,+ creates `~/.9router`, and runs the container with `--restart unless-stopped`,+ `-p 20128:20128`, and `~/.9router:/app/data`.-The UI keeps a manual install command visible as a recovery path if automation cannot work-on another host.+A domain is **not an install prerequisite**. In particular, 9Router is usable through the+VPS public IP immediately after its health check succeeds. Domain-provider integrations+(Cloudflare, Hostinger, etc.) are a separate optional concern and are not called by the+managed-app installer.++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@@ -99,10 +125,7 @@ abandoned before invoking the upstream updater.- 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;-- MSO deliberately does **not** combine a restored state snapshot with an automatic Hermes- branch/version pin, because Hermes' git/stash behaviour can overwrite the state just- restored.+- branch switching exists upstream but is not presented as an ordinary channel menu.### OpenClaw@@ -111,8 +134,16 @@ abandoned before invoking the upstream updater.- normal update restarts and verifies the app rather than leaving new bytes behind an oldprocess.-Update commands use argv arrays, not shell interpolation. User-supplied branch/channel/tag-values pass explicit validation first.+### 9Router++- `/api/version` supplies current/latest/update-available state;+- apply pulls the configured Docker image and recreates the `9router` container;+- the `~/.9router` data mount is preserved across recreation;+- upstream's `latest` image 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@@ -125,53 +156,53 @@ Snapshots live under:They may contain credentials and should be protected like the app's original state. Thesnapshot directory is private and its manifest is `0600`.-Snapshots skip symlinks and recursively exclude reinstallable/cache trees:--- `node_modules`-- `.venv`-- `venv`-- `__pycache__`-- `.git`-- `.cache`-- `backups`-+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 implemented and intentionally conservative.+Restore is intentionally conservative.1. MSO must prove the app is stopped; an uncertain systemd reading is a refusal.2. Backup id and manifest must identify this app and its current state directory.3. Target state directory must be a real safe directory, not a symlink or home ancestor.4. MSO checks the snapshot/target trees for symlink collisions **before** writing.-5. MSO first creates a `pre-restore` safety snapshot of the current state.+5. MSO first creates a `pre-restore` safety snapshot of current state.6. Snapshot files overwrite matching files.7. Files created after the snapshot are **not deleted**.-8. Excluded reinstallable/cache directories above were never in the snapshot and therefore- are not restored.+8. Excluded reinstallable/cache directories were never in the snapshot and are not restored.-That means restore is an overwrite restore, not a byte-for-byte directory replacement. The-result explicitly reports the safety-backup id and excluded content.+Restore is therefore an overwrite restore, not a byte-for-byte directory replacement.## 8. Uninstall-MSO only exposes conservative upstream uninstall scopes and takes a backup first.+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 `9router` container. The image and `~/.9router`+ state 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.-- Hermes removal keeps its state/config by default; MSO does not expose the destructive- full-state removal flag.-- OpenClaw removal targets its gateway service + local state; MSO does not add the workspace- removal scope.-- The UI can preview the upstream removal when the installed CLI proves it supports the- dry-run flag, and server-side confirmation is still required for a real removal.+## 9. Browser access and dashboard origin boundary-A later reinstall is a fresh installation; use the MSO snapshot if you need the previous-credentials/pairings/history back.+**Lifecycle does not require a domain.** These are separate concerns:-## 9. Dashboard origin boundary+1. **Runtime management** — install/start/stop/update/backup/uninstall; no DNS required.+2. **Direct public access** — currently used by 9Router because its server distribution is+ deliberately published on host port `20128`; MSO derives a globally-routable IPv4 from+ local network interfaces and returns `publicDashboardUrl`.+3. **Embedded dashboard access** — optional split-origin mode for a vendor UI shown inside+ MSO.-The safe default is **no embedded vendor dashboard**. To embed them, configure both halves-of one split-origin decision:+The safe embedded-dashboard default is **off**. To opt in, configure all parts of one+split-origin decision:```dotenvNEXT_PUBLIC_MANAGED_APP_HOST_TEMPLATE={id}.mso.example.com@@ -179,56 +210,63 @@ OS_SESSION_COOKIE_DOMAIN=.mso.example.comOS_PUBLIC_ORIGIN=https://mso.example.com```-Then route only the known app hostnames to the same MSO process. Each managed-app hostname-is rewritten exclusively into that app's proxy; cockpit pages/API/static chunks are not-served there.+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.```mermaidflowchart LR- TOP[https://mso.example.com] -->|iframe| HH[https://hermes.mso.example.com]- TOP -->|iframe| OH[https://openclaw.mso.example.com]+ 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]- HH -. cross-origin realm .-> TOP- OH -. cross-origin realm .-> TOP+ NH -->|MSO proxy| N[9Router loopback]+ N -. no DNS required .-> PI[http://public-ip:20128]```-Why this exists: vendor SPAs need `allow-same-origin` to work. If the vendor JavaScript-shared the cockpit origin, it would have the owner's browser realm and session. A separate-hostname makes `window.top` cross-origin. This is a browser-realm boundary only; a plugin-installed **inside Hermes/OpenClaw** still runs with that daemon's host privileges.+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.-There is no supported same-origin dashboard fallback. If the two split-origin environment-variables are unset, MSO leaves vendor dashboards unembedded and the management UI remains-usable.+Never map an arbitrary wildcard hostname to MSO under the session-cookie domain. Provision+only explicit names you intend to serve. Setting the cookie domain without the matching host+gating widens where the session credential is sent.-## 10. Proxy properties+## 10. 9Router distribution and ownership-The dashboard proxy is not a generic forward proxy. It resolves only the catalogued-loopback upstream for the selected managed app. It rewrites response headers and cookies-for the app host, strips/adjusts headers that would block the intended frame, and applies a-CSP that keeps the upstream app within its own realm while allowing the cockpit to frame-it.+Upstream's npm package remains a valid desktop/local way to run 9Router:-Never map an arbitrary wildcard hostname to MSO under the cookie domain. Provision only-hostnames you explicitly intend to serve.+```bash+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.-## 11. Project ingress is a separate feature+See [`9ROUTER-INTEGRATION.md`](./9ROUTER-INTEGRATION.md) for the app-specific contract.-`OS_PROJECT_INGRESS_ROUTES` is not part of Hermes/OpenClaw dashboard management. It is a-generic opt-in seam for exact project-owned POST callbacks. It defaults empty, is capped at-eight exact routes, targets loopback services only, and applies an HMAC-V2-shaped request-prefilter. The target project still owns the real secret verification.+## 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-- state says "not installed" but you know it is running → check whether MSO can reach the- user's systemd bus; do not rerun an installer until detection is trustworthy;-- dashboard frame missing but service is healthy → split-origin config/DNS/proxying may be- intentionally absent; the Details surface still works;+- app says "not installed" but you know it exists → check systemd-user visibility/detection+ evidence before rerunning an installer;+- 9Router is healthy but its new `*.mso...` host fails → use the direct public-IP UI first;+ the split-origin host is optional and has independent DNS/TLS/session-cookie requirements;+- 9Router UI button has no public URL → the host has no globally-routable IPv4 on a local+ interface, or the runtime was deliberately changed to loopback/private-only networking;+- 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 any state-path/symlink diagnostic rather than- bypassing the gate;+- restore refused → stop the app and resolve state-path/symlink diagnostics;- long update appears to vanish → reopen Details; job state/transcript is server-side.--See the per-app references for upstream-specific behaviour.diff --git a/docs/PROGRESS.md b/docs/PROGRESS.mdindex 95e9ee77..e30309c5 100644--- a/docs/PROGRESS.md+++ b/docs/PROGRESS.md@@ -9,6 +9,29 @@ Running log of what shipped each phase. Newest at top.> [`docs/README.md`](./README.md) and [`docs/ARCHITECTURE.md`](./ARCHITECTURE.md); keep old> entries intact as historical evidence even when their commands/counts have been superseded.+## 2026-08-25 — 9Router public-IP-first managed-app correction (DONE)++The first 9Router managed-app pass incorrectly coupled the app surface to MSO's optional+split-origin hostname and documented 9Router as Docker-only. Live inspection disproved both+assumptions: the existing container was healthy on host port 20128 and the older standalone+hostname still worked, while the new `9router.mso...` path was an authenticated MSO proxy;+upstream also ships a real npm `9router` CLI. The result made a healthy app look like a DNS+problem and generated an invalid `9router status` terminal command.++The managed server runtime remains Docker by design (upstream's VPS path), but domain/DNS is+now explicitly optional. Definitions can declare a public host port; MSO derives a global+IPv4 locally and advertises 9Router at `http://<public-ip>:20128`. The UI opens that endpoint+as a separate top-level origin rather than attempting insecure same-origin proxying or an+HTTP iframe inside HTTPS. The CLI view starts with read-only Docker logs and never launches a+second 9Router process. Existing standalone domain routing is left untouched. Install/update/+uninstall continue through the Docker adapter and preserve `~/.9router`; dry-run removal is+part of the verification path.++Current managed-app, install, architecture, troubleshooting, env, README, and dedicated+9Router documentation now agree on the three-layer model: runtime management requires no+domain; direct public access is available where intentionally exposed; split-origin DNS/TLS+is optional embedding infrastructure.+## 2026-08-24 — 9Router joins the managed apps (one-click install/update/uninstall) (DONE)Third managed app: 9Router (decolua/9router), the Docker-only AI gateway already servingdiff --git a/docs/README.md b/docs/README.mdindex a2166f02..2b3f2332 100644--- a/docs/README.md+++ b/docs/README.md@@ -26,9 +26,10 @@ machine-verifiable facts. The repository quality gate runs it automatically.| [`MCP.md`](./MCP.md) | MCP/OAuth internals and full external-tool security model || [`CHATGPT-PLUGIN.md`](./CHATGPT-PLUGIN.md) | ChatGPT custom MCP app setup, diagrams, scopes and file bridge || [`CONNECTORS-GATEWAY-INTEGRATION.md`](./CONNECTORS-GATEWAY-INTEGRATION.md) | MSO ↔ connectors-gateway action-name contract |-| [`MANAGED-APPS.md`](./MANAGED-APPS.md) | Hermes/OpenClaw lifecycle, jobs, update, backup/restore, dashboard boundary |+| [`MANAGED-APPS.md`](./MANAGED-APPS.md) | Hermes/OpenClaw/9Router lifecycle, jobs, backup/restore and dashboard access boundary || [`HERMES-INTEGRATION.md`](./HERMES-INTEGRATION.md) | Hermes-specific integration behaviour || [`OPENCLAW-INTEGRATION.md`](./OPENCLAW-INTEGRATION.md) | OpenClaw-specific integration behaviour |+| [`9ROUTER-INTEGRATION.md`](./9ROUTER-INTEGRATION.md) | 9Router Docker/CLI ownership, public-IP-first UI and optional domain embedding || [`MODELS-INTEGRATION.md`](./MODELS-INTEGRATION.md) | Alfa BYOK/custom/Codex provider model || [`SLICE-CATALOG.md`](./SLICE-CATALOG.md) | Current slice/AppShell feature inventory || [`TROUBLESHOOTING.md`](./TROUBLESHOOTING.md) | Symptom → cause → supported recovery |diff --git a/docs/TROUBLESHOOTING.md b/docs/TROUBLESHOOTING.mdindex baa2b98c..64891d8d 100644--- a/docs/TROUBLESHOOTING.md+++ b/docs/TROUBLESHOOTING.md@@ -145,7 +145,7 @@ zoom/pan as appropriate; do not "fix" it by exposing VNC credentials to the clie## Managed applications-### Hermes/OpenClaw is reported "not installed" but you know it exists+### A managed app is reported "not installed" but you know it existsLook for the diagnostic that says MSO cannot reach the owner systemd user bus. Detectionfails closed for install/restore because rerunning an installer or restoring over a live@@ -156,12 +156,19 @@ unknown service is unsafe. Fix the user bus/linger/service environment first.Expected. MSO mounts the vendor dashboard only when there is a live upstream. Start the app;management/log/update actions remain under Details.+### 9Router is healthy, the old hostname works, but a new `9router.mso...` host does not++Use the direct public-IP URL first. A 9Router install does not require the new hostname. The+`*.mso...` route belongs to optional split-origin embedding and has independent DNS/TLS,+`OS_SESSION_COOKIE_DOMAIN`, build-time host-template and re-login requirements. A `401` from+that host does not mean the 9Router container is down.+### App is healthy but dashboard is not embedded-Embedded dashboards are opt-in. Confirm both+Embedded dashboards are opt-in. Confirm`NEXT_PUBLIC_MANAGED_APP_HOST_TEMPLATE` and `OS_SESSION_COOKIE_DOMAIN`, DNS/TLS for the-explicit app hosts, and sign in again after changing the cookie domain. With both variables-unset, no vendor dashboard is served by design.+explicit app hosts, and sign in again after changing the cookie domain. With those variables+unset, no vendor iframe is served by design. 9Router can still expose its direct public-IP UI.### Update fails before invoking the upstream updaterdiff --git a/frontend/slices/managed-apps/app.tsx b/frontend/slices/managed-apps/app.tsxindex 569d18c7..8117972b 100644--- a/frontend/slices/managed-apps/app.tsx+++ b/frontend/slices/managed-apps/app.tsx@@ -186,7 +186,7 @@ function ManagedAppsSurface({ focus }: { focus: ManagedAppId }) {</p></Hero>) : (- <ManagedFeatureApp feature={feature} />+ <ManagedFeatureApp feature={feature} publicDashboardUrl={app.publicDashboardUrl} />)}</div></div>diff --git a/frontend/slices/managed-apps/feature-app.tsx b/frontend/slices/managed-apps/feature-app.tsxindex e315049d..4df94b48 100644--- a/frontend/slices/managed-apps/feature-app.tsx+++ b/frontend/slices/managed-apps/feature-app.tsx@@ -7,15 +7,17 @@ import { Terminal } from "@/features/os-terminal";import type { ManagedAppFeature } from "@/lib/managed-apps/types";import { cliCommand, featureSource } from "./feature-cli";-export function ManagedFeatureApp({ feature }: AppProps & { feature: ManagedAppFeature }) {- const source = featureSource(feature);+export function ManagedFeatureApp({ feature, publicDashboardUrl }: AppProps & { feature: ManagedAppFeature; publicDashboardUrl?: string | null }) {+ const embeddedSource = featureSource(feature);+ const directSource = publicDashboardUrl ?? null;+ const uiAvailable = Boolean(directSource || embeddedSource);const command = cliCommand(feature);- // No dashboard origin = no vendor UI here at all, so the CLI is not a fallback, it is- // the view. With an origin, the vendor UI is always the opening view: the gateway- // sockets both dashboards drive now ride the proxy (they did not when this defaulted- // OpenClaw to a terminal), so there is no longer a surface that opens dead.+ // A direct public source is intentionally preferred when present: it works on a+ // fresh VPS without DNS/TLS and is already a separate browser origin. We do NOT+ // iframe its http:// URL inside an https:// cockpit (mixed content), and we do+ // NOT fall back to a same-origin proxy (that would give vendor JS the MSO realm).const [generation, setGeneration] = useState(0);- const [view, setView] = useState<"ui" | "cli">(() => (source ? "ui" : "cli"));+ const [view, setView] = useState<"ui" | "cli">(() => (uiAvailable ? "ui" : "cli"));const reload = useCallback(() => setGeneration((value) => value + 1), []);@@ -24,13 +26,13 @@ export function ManagedFeatureApp({ feature }: AppProps & { feature: ManagedAppF{/* No name row: the window header above already says which app this is. Repeating itcost a 48px band on every mount and pushed the app itself down the screen. */}<header className="flex h-9 shrink-0 items-center justify-end gap-1.5 border-b border-border px-2">- {source ? (+ {uiAvailable ? (<button type="button" onClick={() => setView((current) => (current === "ui" ? "cli" : "ui"))} className="inline-flex items-center gap-1.5 rounded-md border border-border px-2 py-1.5 text-xs text-muted-foreground hover:text-foreground" aria-label="Toggle upstream UI or CLI"><TerminalSquare className="size-3.5" />{view === "ui" ? "CLI" : "UI"}</button>) : null}- {source ? (+ {uiAvailable ? (<>- <button type="button" onClick={reload} className="rounded-md border border-border p-2 text-muted-foreground hover:text-foreground" aria-label="Refresh feature"><RefreshCw className="size-3.5" /></button>- <a href={source} target="_blank" rel="noreferrer" className="rounded-md border border-border p-2 text-muted-foreground hover:text-foreground" aria-label="Open feature in dedicated tab"><ExternalLink className="size-3.5" /></a>+ {!directSource ? <button type="button" onClick={reload} className="rounded-md border border-border p-2 text-muted-foreground hover:text-foreground" aria-label="Refresh feature"><RefreshCw className="size-3.5" /></button> : null}+ <a href={directSource ?? embeddedSource ?? undefined} target="_blank" rel="noreferrer" className="rounded-md border border-border p-2 text-muted-foreground hover:text-foreground" aria-label="Open feature in dedicated tab"><ExternalLink className="size-3.5" /></a></>) : null}</header>@@ -46,24 +48,34 @@ export function ManagedFeatureApp({ feature }: AppProps & { feature: ManagedAppFterminal, and a terminal is indistinguishable from a dashboard that broke. Itreads as a fault in the app and sends the operator to look at the app. It is not:it is a deployment that serves no dashboards, and only this file knows that. */}- {!source ? (+ {!uiAvailable ? (<p className="shrink-0 border-b border-border px-3 py-1.5 text-[11px] leading-snug text-muted-foreground">- No dashboard on this deployment — the CLI below is the view.{" "}- <span className="font-mono">NEXT_PUBLIC_MANAGED_APP_HOST_TEMPLATE</span> is unset, so{" "}- {feature.applicationId} has no host of its own to be framed from. Setting it needs a- rebuild, not just a restart. See docs/MANAGED-APPS.md §5.+ No browser UI is exposed by this deployment, so the CLI below is the view. A managed app can work without a domain; split-origin dashboard hosts are optional.</p>) : null}- {view === "cli" || !source ? (+ {view === "cli" || !uiAvailable ? (<div className="min-h-0 flex-1"><Suspense fallback={null}><Terminal initialCommand={command} /></Suspense></div>+ ) : directSource ? (+ <div className="flex h-full min-h-0 items-center justify-center p-6">+ <div className="w-full max-w-lg rounded-xl border border-border bg-card p-5 shadow-sm">+ <div className="flex items-center gap-2 text-sm font-semibold"><ExternalLink className="size-4" />{feature.title} UI</div>+ <p className="mt-2 text-xs leading-relaxed text-muted-foreground">+ This server exposes the app directly on its public IP, so no domain or DNS provider is required. Open it as a separate origin; HTTPS MSO cannot safely embed this HTTP endpoint.+ </p>+ <code className="mt-3 block overflow-x-auto rounded-md bg-muted px-3 py-2 text-[11px]">{directSource}</code>+ <a href={directSource} target="_blank" rel="noreferrer" className="mt-4 inline-flex items-center gap-2 rounded-md bg-primary px-3 py-2 text-xs font-medium text-primary-foreground">+ <ExternalLink className="size-3.5" /> Open {feature.title}+ </a>+ </div>+ </div>) : (<iframekey={generation}- src={source}+ src={embeddedSource ?? undefined}title={`${feature.applicationId} ${feature.title}`}className="min-h-0 flex-1 border-0 bg-background"// allow-same-origin stays, and is the whole point: these SPAs need their own@@ -102,6 +114,6 @@ export function ManagedFeatureApp({ feature }: AppProps & { feature: ManagedAppF// NoDashboardPanel lived here and explained NEXT_PUBLIC_MANAGED_APP_HOST_TEMPLATE at// length. Deleted: it was unreachable (see the render branch above), and a deployment with-// no dashboard origin gets the CLI — which is the app's real surface there, not a-// consolation prize that needs three sentences of apology. The reasoning it carried lives-// in featureSource() in feature-cli.ts, where the decision is actually made.+// no browser UI gets the CLI. Public-port apps can instead advertise a direct,+// separate-origin URL without requiring split-origin DNS; featureSource() remains the+// embedded-dashboard decision for apps that do use dedicated hosts.diff --git a/frontend/slices/managed-apps/feature-cli.test.ts b/frontend/slices/managed-apps/feature-cli.test.tsnew file mode 100644index 00000000..3283d65a--- /dev/null+++ b/frontend/slices/managed-apps/feature-cli.test.ts@@ -0,0 +1,13 @@+import { describe, expect, it } from "vitest";+import { cliCommand, dashboardFeature } from "./feature-cli";++describe("managed app CLI launch commands", () => {+ it("never starts a second 9Router server", () => {+ expect(cliCommand(dashboardFeature("9router", "9Router"))).toBe("docker logs --tail 80 9router");+ });++ it("keeps the upstream read-only status command for CLI-managed apps", () => {+ expect(cliCommand(dashboardFeature("hermes", "Hermes"))).toBe("hermes status");+ expect(cliCommand(dashboardFeature("openclaw", "OpenClaw"))).toBe("openclaw status");+ });+});diff --git a/frontend/slices/managed-apps/feature-cli.ts b/frontend/slices/managed-apps/feature-cli.tsindex 1020e1b1..4453b0cb 100644--- a/frontend/slices/managed-apps/feature-cli.ts+++ b/frontend/slices/managed-apps/feature-cli.ts@@ -11,12 +11,13 @@ export function dashboardFeature(id: ManagedAppId, title: string): ManagedAppFeareturn { id: `${id}:overview`, applicationId: id, title, route: "/", source: "nav-bundle", available: true };}-/** The CLI the window falls back to when no dashboard origin is configured, and what the- * UI/CLI toggle shows. `status` only: it exists on both (verified on this host against- * `hermes --help` / `openclaw --help`) and only reads. Nothing here may be a verb that- * starts WRITING unasked — `openclaw config`, `openclaw doctor` and `hermes model` all- * do, which is why this is a fixed command and not a lookup the caller can widen. */+/** Safe read-only command shown when switching a managed-app window to CLI.+ * Hermes/OpenClaw expose `status`. 9Router does NOT: its upstream CLI starts the+ * server when invoked, while MSO manages the Docker runtime, so auto-running it+ * would race the container for port 20128. Docker logs are the useful read-only+ * server CLI surface and leave the terminal interactive afterwards. */export function cliCommand(feature: ManagedAppFeature): string {+ if (feature.applicationId === "9router") return "docker logs --tail 80 9router";return `${feature.applicationId} status`;}diff --git a/lib/managed-apps/catalog.ts b/lib/managed-apps/catalog.tsindex a09fe698..662095f4 100644--- a/lib/managed-apps/catalog.ts+++ b/lib/managed-apps/catalog.ts@@ -48,16 +48,21 @@ const definitions = {id: "9router",name: "9Router",description: "9Router AI gateway — one endpoint routing coding agents across 40+ providers",- // No upstream CLI exists: 9Router ships only a Docker image. The command is a- // wrapper script in this repo speaking the verbs the adapter drives- // (--version / check / update / uninstall), which is why commandProvesInstall- // is false — the script exists on every checkout, installed or not.+ // Upstream ships BOTH an npm CLI and Docker images. MSO deliberately manages+ // the Docker form on servers/VPSes (the upstream README recommends Docker for+ // that case). `command` is therefore MSO's lifecycle/update adapter, not the+ // upstream `9router` launcher. commandProvesInstall stays false because this+ // repo-owned adapter exists on every checkout, installed or not.command: join(process.cwd(), "scripts", "managed-app-9router"),commandProvesInstall: false,serviceNames: [],containerNames: ["9router"],dashboardUrl: process.env.NINE_ROUTER_DASHBOARD_URL ?? "http://127.0.0.1:20128",healthPath: "/api/health",+ // The Docker install publishes this port on 0.0.0.0. That gives a fresh MSO+ // installation a usable UI without requiring DNS, TLS or a domain provider.+ // Embedding inside HTTPS MSO remains a separate optional split-origin feature.+ publicPort: 20128,stateDirName: ".9router",gradient: "linear-gradient(160deg,#0ea5e9,#2563eb)",},diff --git a/lib/managed-apps/install.test.ts b/lib/managed-apps/install.test.tsindex 204a169d..85868b0a 100644--- a/lib/managed-apps/install.test.ts+++ b/lib/managed-apps/install.test.ts@@ -34,6 +34,7 @@ const view = (installed: boolean): ManagedAppView =>healthy: null,version: null,dashboardAvailable: false,+ publicDashboardUrl: null,diagnostic: null,supportedActions: [],}) as ManagedAppView;diff --git a/lib/managed-apps/manager.test.ts b/lib/managed-apps/manager.test.tsindex ab473393..75a84686 100644--- a/lib/managed-apps/manager.test.ts+++ b/lib/managed-apps/manager.test.ts@@ -44,6 +44,37 @@ afterEach(() => {vi.restoreAllMocks();});+describe("public-IP-first dashboard access", () => {+ it("advertises 9Router on a globally routable host interface without requiring DNS", async () => {+ vi.spyOn(os, "networkInterfaces").mockReturnValue({+ eth0: [+ { address: "10.0.0.5", netmask: "255.0.0.0", family: "IPv4", mac: "00:00:00:00:00:00", internal: false, cidr: "10.0.0.5/8" },+ { address: "76.13.23.37", netmask: "255.255.255.0", family: "IPv4", mac: "00:00:00:00:00:01", internal: false, cidr: "76.13.23.37/24" },+ ],+ });+ systemctl({});+ vi.mocked(commandExists).mockImplementation(async (command: string) => command === "docker");+ vi.mocked(runProgram).mockImplementation(async (command: string, args: readonly string[]) => {+ if (command === "systemctl") return NOT_FOUND;+ if (command === "docker" && args[0] === "ps") return ok("9router\n");+ if (command === "docker" && args[0] === "inspect") return ok("true\n");+ return ok("");+ });+ vi.mocked(resolveCommand).mockResolvedValue(null);++ const view = await getManagedApp("9router");+ expect(view.publicDashboardUrl).toBe("http://76.13.23.37:20128");+ });++ it("does not invent a public URL for loopback-only managed apps", async () => {+ vi.spyOn(os, "networkInterfaces").mockReturnValue({+ eth0: [{ address: "76.13.23.37", netmask: "255.255.255.0", family: "IPv4", mac: "00:00:00:00:00:01", internal: false, cidr: "76.13.23.37/24" }],+ });+ systemctl({ "hermes-dashboard.service": ACTIVE });+ expect((await getManagedApp("hermes")).publicDashboardUrl).toBeNull();+ });+});+describe("systemd detection tells a stopped unit from one that does not exist", () => {it("skips a not-found unit and detects the next configured name", async () => {// OpenClaw's real shape: the first catalog name never existed on this host.diff --git a/lib/managed-apps/manager.ts b/lib/managed-apps/manager.tsindex d0ba4144..dba4f273 100644--- a/lib/managed-apps/manager.ts+++ b/lib/managed-apps/manager.ts@@ -1,4 +1,5 @@import "server-only";+import os from "node:os";import { createBackup } from "./backups";import { getManagedAppDefinition, listManagedAppDefinitions } from "./catalog";import { acquireOperation, activeOperation, releaseOperation } from "./lock";@@ -71,6 +72,36 @@ async function health(definition: ManagedAppDefinition): Promise<boolean | null>}}+/** Globally-routable IPv4 only. Private/CGNAT/link-local addresses are useful for+ * MSO's internal proxy but are not the "works without a domain" address a user+ * can open from their own browser. No external IP-discovery service is called. */+function isPublicIpv4(address: string): boolean {+ const parts = address.split(".").map(Number);+ if (parts.length !== 4 || parts.some((part) => !Number.isInteger(part) || part < 0 || part > 255)) return false;+ const [a, b] = parts;+ if (a === 0 || a === 10 || a === 127 || a >= 224) return false;+ if (a === 100 && b >= 64 && b <= 127) return false; // RFC 6598 CGNAT+ if (a === 169 && b === 254) return false;+ if (a === 172 && b >= 16 && b <= 31) return false;+ if (a === 192 && b === 168) return false;+ return true;+}++export function hostPublicIpv4(): string | null {+ for (const addresses of Object.values(os.networkInterfaces())) {+ for (const address of addresses ?? []) {+ if (address.family === "IPv4" && !address.internal && isPublicIpv4(address.address)) return address.address;+ }+ }+ return null;+}++function directDashboardUrl(definition: ManagedAppDefinition): string | null {+ if (!definition.publicPort) return null;+ const address = hostPublicIpv4();+ return address ? `http://${address}:${definition.publicPort}` : null;+}+// `--version` forks the app's own binary, which is not free (hermes: ~0.44 s of CPU// per call on this host) — and the Managed Apps panel re-polls every 10 s, for a// string that only changes on upgrade. Cached per app id; performManagedAppAction@@ -124,6 +155,7 @@ export async function getManagedApp(id: ManagedAppId): Promise<ManagedAppView> {healthy: isHealthy,version: await version(definition),dashboardAvailable: isRunning && isHealthy !== false,+ publicDashboardUrl: directDashboardUrl(definition),supportedActions: actionsFor(installation),// Only ever attached to a NEGATIVE reading. An app detected as present has// been seen, and nothing about the bus can make that observation wrong.diff --git a/lib/managed-apps/types.ts b/lib/managed-apps/types.tsindex 3de1c125..424957de 100644--- a/lib/managed-apps/types.ts+++ b/lib/managed-apps/types.ts@@ -32,6 +32,11 @@ export interface ManagedAppDefinition {* on every checkout — detection must rest on its container alone, or an* uninstalled 9Router reads as "package" and Install is refused forever. */commandProvesInstall?: boolean;+ /** Optional host port intentionally exposed by this managed runtime. MSO uses it+ * only to advertise a direct, separate-origin UI when this machine has a+ * globally routable IPv4 address. It is never used as the internal health+ * target, and it does not imply that a domain exists. */+ publicPort?: number;}export interface ManagedAppView {@@ -44,6 +49,10 @@ export interface ManagedAppView {healthy: boolean | null;version: string | null;dashboardAvailable: boolean;+ /** Direct browser URL when the runtime deliberately exposes its UI on a public+ * host port. null for loopback-only apps and hosts without a public interface.+ * This is an access convenience, not the upstream URL MSO trusts for health. */+ publicDashboardUrl: string | null;supportedActions: ManagedAppAction[];/** Why this reading may be wrong, when MSO knows that it might be.*diff --git a/lib/os-api/http-adapter.test.ts b/lib/os-api/http-adapter.test.tsindex 228c6bd4..1f87102e 100644--- a/lib/os-api/http-adapter.test.ts+++ b/lib/os-api/http-adapter.test.ts@@ -33,6 +33,7 @@ const view = (id: string, state: string) => ({healthy: state === "running",version: null,dashboardAvailable: state === "running",+ publicDashboardUrl: null,diagnostic: null,supportedActions: ["start", "stop", "restart", "backup"],});diff --git a/scripts/managed-app-9router b/scripts/managed-app-9routerindex 6bc63411..f7f707d5 100755--- a/scripts/managed-app-9router+++ b/scripts/managed-app-9router@@ -1,6 +1,8 @@#!/usr/bin/env bash-# The "CLI" for 9Router, which ships no CLI of its own — only a Docker image-# (decolua/9router). lib/managed-apps drives every app through one adapter+# MSO's lifecycle adapter for the Docker/server distribution of 9Router. Upstream+# ALSO ships an npm `9router` CLI; MSO intentionally does not use that launcher to+# own the server because invoking it starts another runtime. lib/managed-apps drives+# every managed app through one adapter# contract (--version / check / update / uninstall), so this script speaks it.# The catalog points `command` here with commandProvesInstall: false, because# this file exists on every checkout whether or not 9Router is installed.diff --git a/scripts/managed-app-install b/scripts/managed-app-installindex 80740647..f16f457e 100755--- a/scripts/managed-app-install+++ b/scripts/managed-app-install@@ -42,9 +42,10 @@ hermes | openclaw | 9router) ;;;;esac-# 9Router is a Docker container, not a systemd user unit — the user-bus-# preflight below protects installs it will never perform, and failing on it-# would block a docker-only install for no reason. Hand off and stop here.+# MSO installs the Docker/server distribution of 9Router (upstream also has an npm+# CLI, but Docker is the documented VPS path). It needs no systemd user unit, so+# the user-bus preflight below would only create a false install dependency. Hand+# off to the Docker adapter and stop here.if [ "$APP" = "9router" ]; thenexec "$(dirname "$0")/managed-app-9router" installfi