Browser-based graphical shell and control plane for a Linux server you own — real terminal, file manager, live metrics and BYOK AI in one mobile-first workspace. Next.js 16 · React 19 · node-pty · Tailwind v4 · shadcn/ui. Public alpha, self-hosted.
TypeScript browser-shellcontrol-planefile-managerhomelabmobile-firstnextjsptyreactself-hostedserver-managementshadcn-uisysadmintailwindcssterminaltypescriptvpsweb-desktopweb-terminal
feat(managed-apps): preflight install backend on host
Rahmande27e7d254dc
diff --git a/docs/CHANGELOG.md b/docs/CHANGELOG.mdindex 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 Aboutdiff --git a/docs/MANAGED-APPS.md b/docs/MANAGED-APPS.mdindex 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 experiencediff --git a/docs/PROGRESS.md b/docs/PROGRESS.mdindex 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 safetyAn Android tablet with supported arm64/x86_64 architecture can host the MSO Linuxdiff --git a/lib/managed-apps/catalog.ts b/lib/managed-apps/catalog.tsindex 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 managesdiff --git a/lib/managed-apps/host-compatibility.test.ts b/lib/managed-apps/host-compatibility.test.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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;