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): embed 9router existing domain

Rahman9c0a4ff560c4
diff --git a/.env.example b/.env.example
index b03b481d..d427e93d 100644
--- a/.env.example
+++ b/.env.example
@@ -75,6 +75,10 @@ OS_SESSION_SECRET=
# HERMES_DASHBOARD_URL=http://127.0.0.1:9119
# OPENCLAW_DASHBOARD_URL=http://127.0.0.1:18789
# NINE_ROUTER_DASHBOARD_URL=http://127.0.0.1:20128
+# Existing browser-facing 9Router URL, if the deployment already owns one. This is
+# preferred for the in-shell UI; do not create a new subdomain just because MSO can.
+# Without it, MSO may use its split-origin host or the public-IP:20128 fallback.
+# NINE_ROUTER_PUBLIC_URL=https://9-router.example.com
# Hermes install home. Default ~/.hermes. Absolute, or "~/…" for the home of the
# user running mso. This is the tree the managed-app backup action copies.
# HERMES_HOME=/home/you/.hermes
diff --git a/README.md b/README.md
index 1862f161..3be257b7 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, 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).
+- **Manage other apps on the box** — detect, start/stop/restart, health, version, logs, and state backups for separate applications you already run (Hermes, OpenClaw, 9Router), driven through their own systemd/Docker/CLI contracts. 9Router uses its configured application domain as the in-shell dashboard when available, with public IP as the no-domain fallback. See [docs/MANAGED-APPS.md](./docs/MANAGED-APPS.md).
**Work** — code/text editor, browser, and media tools in the same workspace.
@@ -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. 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.
+- Managed-app dashboards are not embedded by default. 9Router can use its direct public-IP port without a domain; when a application hostname is configured, that existing domain becomes its primary in-shell UI. Give each vendor UI a separate explicit hostname such as `hermes.mso.example.com`; there is no supported same-origin iframe mode.
- That boundary is browser-only: a plugin installed into Hermes or OpenClaw runs inside that daemon and can run host commands according to the daemon's own trust model.
- With a model provider configured, Alfa is a tool-calling agent, not a plain chatbot. Its complete current catalog and human-approval contract are generated from `frontend/slices/assistant/host-tools/*` and documented in `frontend/slices/assistant/CONTRACT.md`; avoid copying a tool count into overview docs because the catalog changes independently of MCP.
- Everything Alfa reads — file contents, command output, process lists — is sent to your model provider, and is re-sent on every following turn of the same run. BYOK means you own the key, not that the data stays on the box.
@@ -336,7 +336,7 @@ Not currently supported:
| [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/9ROUTER-INTEGRATION.md](./docs/9ROUTER-INTEGRATION.md) | 9Router server ownership, existing-domain-first in-shell UI and public-IP fallback |
| [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
index 3b499767..2033763b 100644
--- a/docs/9ROUTER-INTEGRATION.md
+++ b/docs/9ROUTER-INTEGRATION.md
@@ -34,7 +34,7 @@ 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
+## Domain-first UI with public-IP fallback
A 9Router installation must not depend on a domain. When MSO sees a globally-routable IPv4
on the host, its managed-app view advertises:
@@ -43,18 +43,27 @@ on the host, its managed-app view advertises:
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.
+The MSO 9Router window offers **UI / CLI**. When a split-origin domain is already configured,
+**UI embeds that dashboard inside the feature shell**, the same way Hermes does. The direct
+public-IP URL is only the fallback for installations without a domain. An HTTP public-IP URL
+is not put in an HTTPS iframe because browsers block mixed content; in that fallback case MSO
+opens the direct UI as a separate origin.
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.
+but it is not part of install health and must never be assumed to exist. If a domain already
+exists, set it explicitly instead of generating another hostname:
-## Optional split-origin embedding
+```dotenv
+NINE_ROUTER_PUBLIC_URL=https://9-router.example.com
+```
+
+Source precedence is: explicit HTTPS `NINE_ROUTER_PUBLIC_URL` → MSO split-origin host →
+public `IP:20128`. An explicit HTTPS app domain is framed directly because it is already a
+separate origin; this also preserves the application's own origin-scoped browser session.
+
+## Split-origin embedding when a domain is configured
-If an operator wants 9Router embedded inside an HTTPS MSO window, use the same explicit
-split-origin contract as other vendor dashboards:
+When the deployment already has a domain, use the same explicit split-origin contract as other vendor dashboards. This is the preferred UI path on that deployment:
```dotenv
NEXT_PUBLIC_MANAGED_APP_HOST_TEMPLATE={id}.mso.example.com
@@ -62,9 +71,10 @@ 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.
+Create only the explicit `9router.mso.example.com` DNS/TLS route and re-authenticate so the
+widened session cookie is actually issued. When this route exists, MSO prefers it over the
+public-IP fallback and renders the dashboard in-shell. A failing domain must still not make the
+running 9Router runtime 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.
diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md
index 7917c518..997063c2 100644
--- a/docs/ARCHITECTURE.md
+++ b/docs/ARCHITECTURE.md
@@ -167,7 +167,7 @@ uninstall them. Long-running install/update/uninstall/restore work is represente
with bounded logs and status.
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
+port 20128; a configured split-origin host is the primary in-shell dashboard, while a global IPv4 lets MSO advertise `http://<public-ip>:20128` as a
direct separate-origin UI. Hermes/OpenClaw stay loopback-only by default.
Embedded vendor dashboards are optional. A split-origin deployment opts in by setting
diff --git a/docs/CHANGELOG.md b/docs/CHANGELOG.md
index ac38748d..bc0edf05 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` embed 9router existing domain
- `managed-apps` make 9router public-ip first
- harden security state and credential guards
diff --git a/docs/INSTALL.md b/docs/INSTALL.md
index 4195c590..3970aa43 100644
--- a/docs/INSTALL.md
+++ b/docs/INSTALL.md
@@ -239,8 +239,9 @@ ChatGPT app; MSO's "Mark ChatGPT refreshed" button is only a local acknowledgeme
## 10. Optional managed-app dashboards
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
+domain-aware on the managed Docker/VPS path: a configured application domain is used as the
+in-shell UI; otherwise, 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.
The safe default is no vendor dashboard on the **MSO cockpit origin**. To opt into
diff --git a/docs/MANAGED-APPS.md b/docs/MANAGED-APPS.md
index 58f078d5..1b478d66 100644
--- a/docs/MANAGED-APPS.md
+++ b/docs/MANAGED-APPS.md
@@ -54,12 +54,13 @@ Opening a managed app first detects it:
- **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
+OpenClaw use their safe split-origin embedded dashboard when configured. 9Router follows the
+same rule: **a configured application domain is the primary in-shell UI**. Its Docker runtime
+also 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.
-MSO intentionally does not iframe `http://<public-ip>:20128` inside an HTTPS cockpit: browsers
+When no domain is configured, MSO intentionally does not iframe `http://<public-ip>:20128` inside an HTTPS cockpit: browsers
block that as mixed content. It also does not proxy a vendor SPA under the cockpit origin,
because a same-origin SPA with `allow-same-origin` could reach the owner's MSO session/API.
@@ -195,10 +196,10 @@ confirmation is still required for a real removal.
**Lifecycle does not require a domain.** These are separate concerns:
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
+2. **Direct public access** — fallback for 9Router when no embeddable domain is configured; 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
+3. **Embedded dashboard access** — preferred when configured: split-origin mode for a vendor UI shown inside
MSO.
The safe embedded-dashboard default is **off**. To opt in, configure all parts of one
@@ -261,8 +262,7 @@ the real secret verification.
- 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 is healthy but its configured `*.mso...` host fails → diagnose DNS/TLS/session-cookie state; the runtime remains healthy and the direct public-IP UI is the fallback;
- 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
diff --git a/docs/PROGRESS.md b/docs/PROGRESS.md
index e30309c5..f61f807f 100644
--- a/docs/PROGRESS.md
+++ b/docs/PROGRESS.md
@@ -9,6 +9,23 @@ 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 configured-domain UI + official icon correction (DONE)
+
+The first public-IP fallback pass made the fallback the preference: because every managed
+9Router container publishes port 20128, `publicDashboardUrl` was always present and the UI
+selected it before the already-configured split-origin host. On deployments such as this one
+with `{id}.mso.rahmanef.com`, that replaced the real in-shell dashboard with a card that only
+opened a new tab. Source precedence is now explicit: configured split-origin domain first,
+public IP only when no embeddable domain exists. UI therefore renders the 9Router dashboard
+inside the same managed-feature iframe shell as Hermes/OpenClaw.
+
+9Router also no longer uses the generic Lucide Route placeholder. MSO copies the official
+`/app/public/icons/icon-512.svg` from the current 9Router Docker distribution into its local
+official-brand asset set and uses it in the shell, launcher, window and Details cards. The
+`sc-all`, `sc-dokploy`, and legacy `si-coder` deployment guidance now records the same
+existing-domain-first/public-IP-fallback contract so future automation does not recreate this
+regression.
+
## 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
diff --git a/docs/README.md b/docs/README.md
index 2b3f2332..425ad6f3 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -29,7 +29,7 @@ machine-verifiable facts. The repository quality gate runs it automatically.
| [`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 |
+| [`9ROUTER-INTEGRATION.md`](./9ROUTER-INTEGRATION.md) | 9Router Docker/CLI ownership, domain-first embedded UI and public-IP fallback |
| [`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/frontend/slices/managed-apps/app.tsx b/frontend/slices/managed-apps/app.tsx
index 8117972b..ce852430 100644
--- a/frontend/slices/managed-apps/app.tsx
+++ b/frontend/slices/managed-apps/app.tsx
@@ -1,7 +1,7 @@
"use client";
import { useCallback, useEffect, useMemo, useState } from "react";
-import { Bot, FileText, Loader2, Play, RefreshCw, Route, Save, SlidersHorizontal, Square, Workflow, type LucideIcon } from "lucide-react";
+import { Bot, FileText, Loader2, Play, RefreshCw, Save, SlidersHorizontal, Square, Workflow, type LucideIcon } from "lucide-react";
import { Button } from "@/components/ui/button";
import type { ManagedAppAction, ManagedAppId, ManagedAppView } from "@/lib/managed-apps/types";
import { dashboardFeature } from "./feature-cli";
@@ -85,15 +85,21 @@ export function NineRouterApp() {
const NAME: Record<ManagedAppId, string> = { hermes: "Hermes", openclaw: "OpenClaw", "9router": "9Router" };
-const MARK: Record<ManagedAppId, { Icon: LucideIcon; tone: string }> = {
+const MARK: Record<ManagedAppId, { Icon?: LucideIcon; tone?: string; artwork?: string }> = {
hermes: { Icon: Bot, tone: "text-violet-400" },
openclaw: { Icon: Workflow, tone: "text-orange-400" },
- "9router": { Icon: Route, tone: "text-sky-400" },
+ "9router": { artwork: "/brand/official/9router.webp" },
};
function AppMark({ id, className }: { id: ManagedAppId; className?: string }) {
- const { Icon, tone } = MARK[id];
- return <Icon className={`${className ?? "size-4"} ${tone}`} />;
+ const mark = MARK[id];
+ if (mark.artwork) {
+ // Official upstream artwork; keep it identical across every shell and Details card.
+ // eslint-disable-next-line @next/next/no-img-element
+ return <img src={mark.artwork} alt="" aria-hidden className={`${className ?? "size-4"} object-contain`} draggable={false} />;
+ }
+ const Icon = mark.Icon!;
+ return <Icon className={`${className ?? "size-4"} ${mark.tone ?? ""}`} />;
}
const ICON: Record<ManagedAppId, React.ReactNode> = {
diff --git a/frontend/slices/managed-apps/feature-app.tsx b/frontend/slices/managed-apps/feature-app.tsx
index 4df94b48..a5689fcb 100644
--- a/frontend/slices/managed-apps/feature-app.tsx
+++ b/frontend/slices/managed-apps/feature-app.tsx
@@ -5,17 +5,18 @@ import { Suspense, useCallback, useState } from "react";
import type { AppProps } from "@/features/appshell";
import { Terminal } from "@/features/os-terminal";
import type { ManagedAppFeature } from "@/lib/managed-apps/types";
-import { cliCommand, featureSource } from "./feature-cli";
+import { cliCommand, dashboardSurfaceSource, featureSource } from "./feature-cli";
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 surface = dashboardSurfaceSource(embeddedSource, publicDashboardUrl);
+ const directSource = surface.kind === "direct" ? surface.source : null;
+ const uiAvailable = surface.source !== null;
const command = cliCommand(feature);
- // 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).
+ // Existing configured domain wins: that split-origin URL is the safe embeddable UI,
+ // exactly like Hermes/OpenClaw. The public-IP URL is only a no-domain fallback. We do
+ // not iframe an http:// public IP inside an https:// cockpit (mixed content), and we
+ // never fall back to a same-origin vendor iframe.
const [generation, setGeneration] = useState(0);
const [view, setView] = useState<"ui" | "cli">(() => (uiAvailable ? "ui" : "cli"));
@@ -32,7 +33,7 @@ export function ManagedFeatureApp({ feature, publicDashboardUrl }: AppProps & {
{uiAvailable ? (
<>
{!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>
+ <a href={surface.source ?? 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>
@@ -75,7 +76,7 @@ export function ManagedFeatureApp({ feature, publicDashboardUrl }: AppProps & {
) : (
<iframe
key={generation}
- src={embeddedSource ?? undefined}
+ src={surface.kind === "embedded" ? surface.source ?? undefined : 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
diff --git a/frontend/slices/managed-apps/feature-cli.test.ts b/frontend/slices/managed-apps/feature-cli.test.ts
index 3283d65a..09ab421d 100644
--- a/frontend/slices/managed-apps/feature-cli.test.ts
+++ b/frontend/slices/managed-apps/feature-cli.test.ts
@@ -1,5 +1,5 @@
import { describe, expect, it } from "vitest";
-import { cliCommand, dashboardFeature } from "./feature-cli";
+import { cliCommand, dashboardFeature, dashboardSurfaceSource } from "./feature-cli";
describe("managed app CLI launch commands", () => {
it("never starts a second 9Router server", () => {
@@ -11,3 +11,27 @@ describe("managed app CLI launch commands", () => {
expect(cliCommand(dashboardFeature("openclaw", "OpenClaw"))).toBe("openclaw status");
});
});
+
+
+describe("managed dashboard source precedence", () => {
+
+ it("prefers an existing HTTPS application domain over a generated MSO host", () => {
+ expect(dashboardSurfaceSource("https://9router.mso.example.com/", "https://9-router.example.com")).toEqual({
+ source: "https://9-router.example.com",
+ kind: "embedded",
+ });
+ });
+ it("prefers the configured embedded domain over a public-IP fallback", () => {
+ expect(dashboardSurfaceSource("https://9router.mso.example.com/", "http://203.0.113.10:20128")).toEqual({
+ source: "https://9router.mso.example.com/",
+ kind: "embedded",
+ });
+ });
+
+ it("uses the public-IP URL only when no embedded domain exists", () => {
+ expect(dashboardSurfaceSource(null, "http://203.0.113.10:20128")).toEqual({
+ source: "http://203.0.113.10:20128",
+ kind: "direct",
+ });
+ });
+});
diff --git a/frontend/slices/managed-apps/feature-cli.ts b/frontend/slices/managed-apps/feature-cli.ts
index 4453b0cb..155bb61d 100644
--- a/frontend/slices/managed-apps/feature-cli.ts
+++ b/frontend/slices/managed-apps/feature-cli.ts
@@ -39,3 +39,18 @@ export function featureSource(feature: ManagedAppFeature): string | null {
const origin = managedAppOrigin(feature.applicationId);
return origin ? `${origin}/${feature.route.replace(/^\/+/, "")}` : null;
}
+
+/** Pick the browser surface without confusing availability with preference.
+ * A configured split-origin host is the primary UI because it can be embedded safely in
+ * the MSO feature shell. A direct public-IP URL is only the no-domain fallback. */
+export function dashboardSurfaceSource(
+ embeddedSource: string | null,
+ publicDashboardUrl: string | null | undefined,
+): { source: string | null; kind: "embedded" | "direct" | "none" } {
+ // An explicit HTTPS app domain is already a safe separate origin and usually carries
+ // the app's existing cookies/session, so do not invent a second MSO subdomain for it.
+ if (publicDashboardUrl?.startsWith("https://")) return { source: publicDashboardUrl, kind: "embedded" };
+ if (embeddedSource) return { source: embeddedSource, kind: "embedded" };
+ if (publicDashboardUrl) return { source: publicDashboardUrl, kind: "direct" };
+ return { source: null, kind: "none" };
+}
diff --git a/frontend/slices/managed-apps/index.ts b/frontend/slices/managed-apps/index.ts
index 2b5dbd5a..96f6db00 100644
--- a/frontend/slices/managed-apps/index.ts
+++ b/frontend/slices/managed-apps/index.ts
@@ -1,12 +1,24 @@
-import { Bot, Route, Workflow, type LucideIcon } from "lucide-react";
-import type { AppDescriptor } from "@/features/os-shell";
+import { Bot, Workflow, type LucideIcon } from "lucide-react";
+import { createElement } from "react";
+import type { AppDescriptor, AppIconComponent } from "@/features/os-shell";
+
+const NineRouterIcon: AppIconComponent = ({ className }) =>
+ // Exact upstream 9Router artwork, copied from the managed Docker image. This file is
+ // intentionally .ts (not .tsx), so use createElement rather than adding a JSX-only rename.
+ createElement("img", {
+ src: "/brand/official/9router.webp",
+ alt: "",
+ "aria-hidden": true,
+ className: className ?? "size-full object-contain",
+ draggable: false,
+ });
type ManagedApp = "hermes" | "openclaw" | "9router";
-const LOOK: Record<ManagedApp, { title: string; icon: LucideIcon; gradient: string; loader: string }> = {
+const LOOK: Record<ManagedApp, { title: string; icon: LucideIcon | AppIconComponent; gradient: string; loader: string }> = {
hermes: { title: "Hermes", icon: Bot, gradient: "linear-gradient(160deg,#8b5cf6,#4f46e5)", loader: "HermesApp" },
openclaw: { title: "OpenClaw", icon: Workflow, gradient: "linear-gradient(160deg,#f97316,#dc2626)", loader: "OpenClawApp" },
- "9router": { title: "9Router", icon: Route, gradient: "linear-gradient(160deg,#0ea5e9,#2563eb)", loader: "NineRouterApp" },
+ "9router": { title: "9Router", icon: NineRouterIcon, gradient: "linear-gradient(160deg,#0ea5e9,#2563eb)", loader: "NineRouterApp" },
};
// Ordinary apps, dock and all. They were `noDock` while MSO could swap its whole shell
diff --git a/frontend/slices/os-shell/brand-marks.test.tsx b/frontend/slices/os-shell/brand-marks.test.tsx
index cd6a4bdb..d1aa43b6 100644
--- a/frontend/slices/os-shell/brand-marks.test.tsx
+++ b/frontend/slices/os-shell/brand-marks.test.tsx
@@ -13,6 +13,7 @@ describe("third-party official app marks", () => {
["camoufox-browser", "/brand/official/camoufox.webp"],
["hermes", "/brand/official/hermes.webp"],
["openclaw", "/brand/official/openclaw.webp"],
+ ["9router", "/brand/official/9router.webp"],
])("keeps %s shell-invariant and official", (id, src) => {
const html = markup(id);
expect(html).toContain(`src="${src}"`);
diff --git a/frontend/slices/os-shell/brand-marks.tsx b/frontend/slices/os-shell/brand-marks.tsx
index 88c991be..868f0991 100644
--- a/frontend/slices/os-shell/brand-marks.tsx
+++ b/frontend/slices/os-shell/brand-marks.tsx
@@ -91,8 +91,10 @@ export const APP_MARKS: Record<string, AppIconComponent> = {
),
hermes: officialMark("/brand/official/hermes.webp"),
openclaw: officialMark("/brand/official/openclaw.webp"),
+ "9router": officialMark("/brand/official/9router.webp"),
};
export const HermesMark = APP_MARKS.hermes;
export const OpenClawMark = APP_MARKS.openclaw;
+export const NineRouterMark = APP_MARKS["9router"];
export const CamoufoxMark = APP_MARKS["camoufox-browser"];
diff --git a/lib/managed-apps/catalog.ts b/lib/managed-apps/catalog.ts
index 662095f4..1db99698 100644
--- a/lib/managed-apps/catalog.ts
+++ b/lib/managed-apps/catalog.ts
@@ -63,6 +63,7 @@ const definitions = {
// 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,
+ publicUrl: process.env.NINE_ROUTER_PUBLIC_URL,
stateDirName: ".9router",
gradient: "linear-gradient(160deg,#0ea5e9,#2563eb)",
},
diff --git a/lib/managed-apps/manager.test.ts b/lib/managed-apps/manager.test.ts
index 75a84686..c9558d4e 100644
--- a/lib/managed-apps/manager.test.ts
+++ b/lib/managed-apps/manager.test.ts
@@ -44,7 +44,7 @@ afterEach(() => {
vi.restoreAllMocks();
});
-describe("public-IP-first dashboard access", () => {
+describe("public-IP dashboard fallback", () => {
it("advertises 9Router on a globally routable host interface without requiring DNS", async () => {
vi.spyOn(os, "networkInterfaces").mockReturnValue({
eth0: [
diff --git a/lib/managed-apps/manager.ts b/lib/managed-apps/manager.ts
index dba4f273..ece4d68e 100644
--- a/lib/managed-apps/manager.ts
+++ b/lib/managed-apps/manager.ts
@@ -97,6 +97,17 @@ export function hostPublicIpv4(): string | null {
}
function directDashboardUrl(definition: ManagedAppDefinition): string | null {
+ const configured = definition.publicUrl?.trim();
+ if (configured) {
+ try {
+ const url = new URL(configured);
+ if ((url.protocol === "https:" || url.protocol === "http:") && !url.username && !url.password) {
+ return configured.replace(/\/$/, "");
+ }
+ } catch {
+ // Bad operator config is not an app-health failure; fall through to the IP path.
+ }
+ }
if (!definition.publicPort) return null;
const address = hostPublicIpv4();
return address ? `http://${address}:${definition.publicPort}` : null;
diff --git a/lib/managed-apps/types.ts b/lib/managed-apps/types.ts
index 424957de..34a84ede 100644
--- a/lib/managed-apps/types.ts
+++ b/lib/managed-apps/types.ts
@@ -37,6 +37,10 @@ export interface ManagedAppDefinition {
* globally routable IPv4 address. It is never used as the internal health
* target, and it does not imply that a domain exists. */
publicPort?: number;
+ /** Existing browser-facing URL owned by this application/deployment, e.g.
+ * https://9-router.example.com. When valid, this is preferred over generated
+ * managed-app hosts and public-IP fallbacks. */
+ publicUrl?: string;
}
export interface ManagedAppView {
@@ -49,9 +53,9 @@ 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. */
+ /** Preferred browser-facing URL outside the MSO cockpit: an explicit configured
+ * application domain when present, otherwise a public-IP:port fallback. null for
+ * loopback-only apps/hosts. This is never the trusted internal health target. */
publicDashboardUrl: string | null;
supportedActions: ManagedAppAction[];
/** Why this reading may be wrong, when MSO knows that it might be.
diff --git a/public/brand/official/9router.webp b/public/brand/official/9router.webp
new file mode 100644
index 00000000..3e026270
Binary files /dev/null and b/public/brand/official/9router.webp differ
diff --git a/public/brand/official/SOURCES.md b/public/brand/official/SOURCES.md
index afe57917..84bcf625 100644
--- a/public/brand/official/SOURCES.md
+++ b/public/brand/official/SOURCES.md
@@ -5,3 +5,4 @@ These WebP files are resized/compressed derivatives of the upstream projects' ow
- Camoufox: `daijro/camoufox` — `additions/browser/branding/camoufox/Assets.xcassets/AppIcon.appiconset/icon_512x512.png`
- Hermes: `NousResearch/hermes-agent` — `apps/desktop/assets/icon.png`
- OpenClaw: `openclaw/openclaw` — `docs/assets/pixel-lobster.svg`
+- 9Router: `decolua/9router` — running `decolua/9router:0.5.55` image `/app/public/icons/icon-512.svg`
diff --git a/scripts/e2e/shell.mjs b/scripts/e2e/shell.mjs
index 1b218241..cb30ca83 100644
--- a/scripts/e2e/shell.mjs
+++ b/scripts/e2e/shell.mjs
@@ -68,7 +68,7 @@ const TITLES = {
files: "Files", browser: "Camoufox", code: "Code", terminal: "Terminal", claude: "Claude Code",
studio: "Image Editor", reel: "Video Editor", viewer: "Preview", store: "App Store", create: "Create App",
monitor: "System Monitor", assistant: "Alfa", links: "Quicklinks", docs: "Docs", settings: "Settings",
- hermes: "Hermes", openclaw: "OpenClaw",
+ hermes: "Hermes", openclaw: "OpenClaw", "9router": "9Router",
};
const IGNORE = [
@@ -228,7 +228,7 @@ async function session(browser, { width, height, label, touch = width < 768, exp
// origin their own frame-ancestors/session policy correctly rejects the iframe,
// so exercise host routing/rendering here without treating that origin mismatch
// as an MSO host-network failure. Their own runtime has separate managed-app tests.
- for (const slug of ["hermes", "openclaw"]) {
+ for (const slug of ["hermes", "openclaw", "9router"]) {
await page.goto(`${BASE}/${slug}`, { waitUntil: "domcontentloaded" });
await page.waitForTimeout(1200);
check(page.url().endsWith(`/${slug}`), `/${slug} managed-app deep-link kept the URL`);