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.

feat(managed-apps): preflight install backend on host

Rahmande27e7d254dc
diff --git a/docs/CHANGELOG.md b/docs/CHANGELOG.md
index 17ebde21..d9e24831 100644
--- a/docs/CHANGELOG.md
+++ b/docs/CHANGELOG.md
@@ -8,6 +8,7 @@ this is the *what*, and it is what Settings → Account → About shows as “Wh
**Added**
+- `managed-apps` preflight install backend on host
- `jev` persist reusable session capsules
- `settings` nest version and updates under About
diff --git a/docs/MANAGED-APPS.md b/docs/MANAGED-APPS.md
index 863c667b..7d8663e3 100644
--- a/docs/MANAGED-APPS.md
+++ b/docs/MANAGED-APPS.md
@@ -31,7 +31,7 @@ flowchart LR
| 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` |
+| Hermes | user systemd (`hermes-dashboard.service`, `hermes-gateway.service`) or pinned Docker fallback | `127.0.0.1:9119` by default | none by default | `~/.hermes` or `HERMES_HOME` |
| OpenClaw | user systemd (`openclaw-gateway.service`) | `127.0.0.1:18789` by default | none by default | `~/.openclaw` |
| 9Router | Docker container `9router` | `127.0.0.1:20128` by default | `http://<public-ip>:20128` when the host has a global IPv4 | `~/.9router` mounted at `/app/data` |
@@ -47,9 +47,13 @@ on hosts without systemd; MSO does not widen 9Router just to compensate. The rep
`scripts/managed-app-9router install` or `mso mapp install 9router`; the safe bind remains
`127.0.0.1:20128` unless the owner explicitly opts into `NINE_ROUTER_EXPOSE_PUBLIC=1`.
-Hermes and OpenClaw depend on a working user systemd bus. Ensure linger, `XDG_RUNTIME_DIR`, and the
-user manager are healthy before install; do not treat a partially available bus as a successful
-half-install.
+OpenClaw needs a working user systemd bus. Hermes uses user systemd when available and can
+fall back to its reviewed Docker runtime if the daemon is accessible to the MSO service user.
+9Router needs an accessible Docker daemon. On a Termux/PRoot host without either backend, MSO
+rejects all three install jobs before downloads; the tablet can still host the MSO core.
+A Linux guest on Windows/macOS follows the same backend checks inside that guest. Ensure linger,
+`XDG_RUNTIME_DIR`, and the user manager are healthy for apps using user systemd; do not treat
+a partially available bus as a successful half-install.
## 2. User experience
diff --git a/docs/PROGRESS.md b/docs/PROGRESS.md
index 1ccc44de..545f9525 100644
--- a/docs/PROGRESS.md
+++ b/docs/PROGRESS.md
@@ -1,3 +1,18 @@
+## 2026-09-27 — Managed app host compatibility preflight
+
+Managed app definitions now declare the installer backends they actually support:
+Hermes user systemd or Docker, OpenClaw user systemd, and 9Router Docker.
+The install API checks the local Linux runtime and reachable backend before
+starting a job or downloading an artifact. This includes Android tablets hosting
+MSO under Ubuntu PRoot: MSO core can run there while applications whose runtime
+backend is unavailable are rejected with a specific reason. The 9Router
+not-installed diagnostic no longer mislabels an accessible Docker host as
+uncertain solely because its user systemd bus is absent.
+
+The Managed Apps documentation matches the reviewed Hermes Docker fallback.
+This step does not add a Docker daemon to Android PRoot or claim those three
+applications can all run on every tablet. Physical host verification remains open.
+
## 2026-09-27 — Portable host installer safety
An Android tablet with supported arm64/x86_64 architecture can host the MSO Linux
diff --git a/lib/managed-apps/catalog.ts b/lib/managed-apps/catalog.ts
index d908c07c..8d59d0e1 100644
--- a/lib/managed-apps/catalog.ts
+++ b/lib/managed-apps/catalog.ts
@@ -13,6 +13,7 @@ export function expandHome(value: string | undefined): string {
const definitions = {
hermes: {
id: "hermes",
+ installBackends: ["user-systemd", "docker"],
name: "Hermes",
description: "Hermes Agent runtime and dashboard",
command: "hermes",
@@ -34,6 +35,7 @@ const definitions = {
},
openclaw: {
id: "openclaw",
+ installBackends: ["user-systemd"],
name: "OpenClaw",
description: "OpenClaw runtime and control surface",
command: "openclaw",
@@ -47,6 +49,7 @@ const definitions = {
},
"9router": {
id: "9router",
+ installBackends: ["docker"],
name: "9Router",
description: "9Router AI gateway — one endpoint routing coding agents across 40+ providers",
// Upstream ships BOTH an npm CLI and Docker images. MSO deliberately manages
diff --git a/lib/managed-apps/host-compatibility.test.ts b/lib/managed-apps/host-compatibility.test.ts
new file mode 100644
index 00000000..9dfa7aed
--- /dev/null
+++ b/lib/managed-apps/host-compatibility.test.ts
@@ -0,0 +1,30 @@
+import { describe, expect, it } from "vitest";
+import { getManagedAppDefinition } from "./catalog";
+import { managedAppInstallSupport } from "./host-compatibility";
+
+describe("managed app install compatibility", () => {
+ const host = (userSystemd: boolean, docker: boolean) =>
+ ({ platform: "linux" as const, userSystemd, docker });
+
+ it("selects only reviewed backends supported by the current Linux host", () => {
+ expect(managedAppInstallSupport(getManagedAppDefinition("hermes"), host(false, true)).backend).toBe("docker");
+ expect(managedAppInstallSupport(getManagedAppDefinition("openclaw"), host(true, true)).backend).toBe("user-systemd");
+ expect(managedAppInstallSupport(getManagedAppDefinition("9router"), host(true, true)).backend).toBe("docker");
+ });
+
+ it("blocks app combinations without the required backend before installing", () => {
+ for (const id of ["hermes", "openclaw", "9router"] as const) {
+ const result = managedAppInstallSupport(getManagedAppDefinition(id), host(false, false));
+ expect(result.supported).toBe(false);
+ expect(result.reason).toMatch(/requires/);
+ }
+ expect(managedAppInstallSupport(getManagedAppDefinition("openclaw"), host(false, true)).supported).toBe(false);
+ expect(managedAppInstallSupport(getManagedAppDefinition("9router"), host(true, false)).supported).toBe(false);
+ });
+
+ it("requires a Linux runtime even when a daemon is reported by the host", () => {
+ expect(managedAppInstallSupport(getManagedAppDefinition("hermes"), {
+ platform: "darwin", userSystemd: true, docker: true,
+ }).supported).toBe(false);
+ });
+});
diff --git a/lib/managed-apps/host-compatibility.ts b/lib/managed-apps/host-compatibility.ts
new file mode 100644
index 00000000..da2d61d2
--- /dev/null
+++ b/lib/managed-apps/host-compatibility.ts
@@ -0,0 +1,31 @@
+import type { ManagedAppDefinition, ManagedAppInstallBackend } from "./types";
+
+export type ManagedAppHostCapabilities = {
+ platform: NodeJS.Platform;
+ userSystemd: boolean;
+ docker: boolean;
+};
+
+export type ManagedAppInstallSupport = {
+ supported: boolean;
+ backend: ManagedAppInstallBackend | null;
+ reason: string | null;
+};
+
+/** The adapter's actual install backends, evaluated before any download/job. */
+export function managedAppInstallSupport(
+ definition: ManagedAppDefinition,
+ host: ManagedAppHostCapabilities,
+): ManagedAppInstallSupport {
+ if (host.platform !== "linux") {
+ return { supported: false, backend: null, reason: "Managed app installers require a Linux runtime on this host." };
+ }
+ for (const backend of definition.installBackends) {
+ if (backend === "user-systemd" && host.userSystemd) return { supported: true, backend, reason: null };
+ if (backend === "docker" && host.docker) return { supported: true, backend, reason: null };
+ }
+ const required = definition.installBackends.includes("user-systemd")
+ ? definition.installBackends.includes("docker") ? "a working user systemd bus or Docker daemon" : "a working user systemd bus"
+ : "a working Docker daemon";
+ return { supported: false, backend: null, reason: `${definition.name} requires ${required} accessible to the MSO service user.` };
+}
diff --git a/lib/managed-apps/install-host.test.ts b/lib/managed-apps/install-host.test.ts
new file mode 100644
index 00000000..63a5d3c8
--- /dev/null
+++ b/lib/managed-apps/install-host.test.ts
@@ -0,0 +1,41 @@
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import type { ManagedAppView } from "./types";
+
+vi.mock("server-only", () => ({}));
+vi.mock("./manager", () => ({ getManagedApp: vi.fn() }));
+vi.mock("./jobs", () => ({ startManagedAppJob: vi.fn() }));
+vi.mock("./docker", () => ({ dockerUsable: vi.fn() }));
+vi.mock("./user-bus", () => ({ userBusUnavailable: vi.fn() }));
+
+import { dockerUsable } from "./docker";
+import { startInstall } from "./install";
+import { startManagedAppJob } from "./jobs";
+import { getManagedApp } from "./manager";
+import { userBusUnavailable } from "./user-bus";
+
+beforeEach(() => {
+ vi.mocked(getManagedApp).mockResolvedValue({ installed: false, diagnostic: null } as ManagedAppView);
+ vi.mocked(startManagedAppJob).mockReset().mockResolvedValue({} as never);
+ vi.mocked(dockerUsable).mockResolvedValue(true);
+ vi.mocked(userBusUnavailable).mockReturnValue(false);
+});
+
+describe("managed app host preflight", () => {
+ it("rejects OpenClaw before starting a job without a user systemd bus", async () => {
+ vi.mocked(userBusUnavailable).mockReturnValue(true);
+ await expect(startInstall("openclaw")).rejects.toThrow(/user systemd bus/);
+ expect(startManagedAppJob).not.toHaveBeenCalled();
+ });
+
+ it("allows Hermes Docker fallback without a user systemd bus", async () => {
+ vi.mocked(userBusUnavailable).mockReturnValue(true);
+ await startInstall("hermes");
+ expect(vi.mocked(startManagedAppJob).mock.calls[0]?.[0].applicationId).toBe("hermes");
+ });
+
+ it("rejects 9Router before starting a job without Docker", async () => {
+ vi.mocked(dockerUsable).mockResolvedValue(false);
+ await expect(startInstall("9router")).rejects.toThrow(/Docker daemon/);
+ expect(startManagedAppJob).not.toHaveBeenCalled();
+ });
+});
diff --git a/lib/managed-apps/install.test.ts b/lib/managed-apps/install.test.ts
index af30b4e0..6510ce02 100644
--- a/lib/managed-apps/install.test.ts
+++ b/lib/managed-apps/install.test.ts
@@ -13,9 +13,12 @@ vi.hoisted(() => {
vi.mock("server-only", () => ({}));
vi.mock("./manager", () => ({ getManagedApp: vi.fn() }));
vi.mock("./jobs", () => ({ startManagedAppJob: vi.fn() }));
-
+vi.mock("./docker", () => ({ dockerUsable: vi.fn() }));
+vi.mock("./user-bus", () => ({ userBusUnavailable: vi.fn() }));
import { startManagedAppJob } from "./jobs";
import { getManagedApp } from "./manager";
+import { dockerUsable } from "./docker";
+import { userBusUnavailable } from "./user-bus";
import { startInstall } from "./install";
import { providersFor } from "./providers";
import type { ManagedAppView } from "./types";
@@ -47,6 +50,8 @@ beforeEach(() => {
mockGet.mockReset();
mockStart.mockResolvedValue({} as never);
mockGet.mockResolvedValue(view(false));
+ vi.mocked(dockerUsable).mockResolvedValue(true);
+ vi.mocked(userBusUnavailable).mockReturnValue(false);
});
describe("install job options", () => {
diff --git a/lib/managed-apps/install.ts b/lib/managed-apps/install.ts
index 7144389c..09de1bef 100644
--- a/lib/managed-apps/install.ts
+++ b/lib/managed-apps/install.ts
@@ -1,6 +1,9 @@
import "server-only";
import path from "node:path";
import { getManagedAppDefinition } from "./catalog";
+import { dockerUsable } from "./docker";
+import { managedAppInstallSupport } from "./host-compatibility";
+import { userBusUnavailable } from "./user-bus";
import { startManagedAppJob } from "./jobs";
import { getManagedApp } from "./manager";
import { managedAppOrigin } from "./origin";
@@ -55,8 +58,16 @@ const BINDS = new Set(["loopback", "lan", "tailnet", "auto"]);
* or a stale page, and re-running one restarts services under whoever is using
* them. Update is the verb for an app that is already there. */
export async function startInstall(id: ManagedAppId, options: InstallOptions = {}): Promise<ManagedAppJob> {
+ const definition = getManagedAppDefinition(id);
const view = await getManagedApp(id);
- if (view.installed) throw new Error(`${getManagedAppDefinition(id).name} is already installed — use Update instead`);
+ if (view.installed) throw new Error(`${definition.name} is already installed — use Update instead`);
+ const support = managedAppInstallSupport(definition, {
+ platform: process.platform,
+ userSystemd: !userBusUnavailable(),
+ docker: definition.installBackends.includes("docker") && await dockerUsable(),
+ });
+ if (!support.supported) throw new Error(support.reason ?? "managed app installer unsupported on this host");
+
// Fail CLOSED on an unreadable reading. This guard's own reason for existing
// (above) is that re-running an installer "restarts services under whoever is
// using them" — and Hermes' upstream installer recreates the venv that the
@@ -64,7 +75,7 @@ export async function startInstall(id: ManagedAppId, options: InstallOptions = {
// cannot see user services is exactly when that is most destructive, so
// "I could not check" must not be treated as "it is not there".
if (view.diagnostic) {
- throw new Error(`cannot determine whether ${getManagedAppDefinition(id).name} is installed — refusing to run the installer. ${view.diagnostic}`);
+ throw new Error(`cannot determine whether ${definition.name} is installed — refusing to run the installer. ${view.diagnostic}`);
}
const env: Record<string, string> = {};
diff --git a/lib/managed-apps/manager.ts b/lib/managed-apps/manager.ts
index 44ad8c8a..70f53563 100644
--- a/lib/managed-apps/manager.ts
+++ b/lib/managed-apps/manager.ts
@@ -157,7 +157,7 @@ export async function getManagedApp(id: ManagedAppId): Promise<ManagedAppView> {
: isRunning
? "running"
: "stopped";
- const dockerFallbackAvailable = id === "hermes" && installation.type === "not-installed" && await dockerUsable();
+ const dockerInstallAvailable = definition.installBackends.includes("docker") && installation.type === "not-installed" && await dockerUsable();
return {
id,
name: definition.name,
@@ -174,7 +174,7 @@ export async function getManagedApp(id: ManagedAppId): Promise<ManagedAppView> {
// been seen, and nothing about the bus can make that observation wrong.
diagnostic:
installation.type === "not-installed" && userBusUnavailable()
- ? dockerFallbackAvailable
+ ? dockerInstallAvailable
? null
: "MSO cannot reach this user's systemd bus, so it cannot see user services. On a systemd host enable user linger and provide XDG_RUNTIME_DIR; on a systemd-less/container host use a supported Docker runtime."
: null,
diff --git a/lib/managed-apps/types.ts b/lib/managed-apps/types.ts
index 34a84ede..b0ccaa06 100644
--- a/lib/managed-apps/types.ts
+++ b/lib/managed-apps/types.ts
@@ -12,7 +12,11 @@ export type ManagedAppState =
| "unhealthy"
| "error";
+export type ManagedAppInstallBackend = "user-systemd" | "docker";
+
export interface ManagedAppDefinition {
+ /** Backends the reviewed install adapter can actually create on this host. */
+ installBackends: readonly ManagedAppInstallBackend[];
id: ManagedAppId;
name: string;
description: string;