Skip to content

armgit / mso

Public Imported from GitHub
0

Browser-based graphical shell and control plane for a Linux server you own — real terminal, file manager, live metrics and BYOK AI in one mobile-first workspace. Next.js 16 · React 19 · node-pty · Tailwind v4 · shadcn/ui. Public alpha, self-hosted.

fix(managed-apps): make 9router public-ip first

Rahman8f5597562f1d
diff --git a/.env.example b/.env.example
index 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 and
diff --git a/README.md b/README.md
index 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 such
as 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 separate
from 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 tra
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)
+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
@@ -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 LR
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<br/>own runtime + data"]
+ 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
@@ -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.md
new file mode 100644
index 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.md
index c35173ec..7917c518 100644
--- a/docs/ARCHITECTURE.md
+++ b/docs/ARCHITECTURE.md
@@ -55,7 +55,7 @@ frontend/slices/ vertical application slices
lib/auth/ login/session/device approval
lib/host/ bounded host capability implementation
lib/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/proxy
lib/skills/ trusted skill discovery and semantic search
scripts/ install, release, checks and service helpers
claude-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 implementation
uses 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 own
dashboard 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 Browser
diff --git a/docs/CHANGELOG.md b/docs/CHANGELOG.md
index 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-23
diff --git a/docs/INSTALL.md b/docs/INSTALL.md
index 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:
```dotenv
NEXT_PUBLIC_MANAGED_APP_HOST_TEMPLATE={id}.mso.example.com
@@ -249,9 +252,10 @@ OS_SESSION_COOKIE_DOMAIN=.mso.example.com
OS_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 mode
diff --git a/docs/MANAGED-APPS.md b/docs/MANAGED-APPS.md
index 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 and
privileges. 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.
```mermaid
flowchart LR
@@ -14,39 +13,59 @@ flowchart LR
M --> 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 --> H
J --> O
+ J --> N
P --> H
P --> 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 user
systemd 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 old
process.
-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. The
snapshot 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:
```dotenv
NEXT_PUBLIC_MANAGED_APP_HOST_TEMPLATE={id}.mso.example.com
@@ -179,56 +210,63 @@ OS_SESSION_COOKIE_DOMAIN=.mso.example.com
OS_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.
```mermaid
flowchart 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.md
index 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 serving
diff --git a/docs/README.md b/docs/README.md
index 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.md
index 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 exists
Look for the diagnostic that says MSO cannot reach the owner systemd user bus. Detection
fails 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 updater
diff --git a/frontend/slices/managed-apps/app.tsx b/frontend/slices/managed-apps/app.tsx
index 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.tsx
index 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 it
cost 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: ManagedAppF
terminal, and a terminal is indistinguishable from a dashboard that broke. It
reads 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>
) : (
<iframe
key={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.ts
new file mode 100644
index 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.ts
index 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): ManagedAppFea
return { 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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-9router
index 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-install
index 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" ]; then
exec "$(dirname "$0")/managed-app-9router" install
fi