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): support Hermes without systemd

Abdurrahman Fakhruld3918cf6bb1d
diff --git a/docs/CHANGELOG.md b/docs/CHANGELOG.md
index 46ba2ca6..21e6d27e 100644
--- a/docs/CHANGELOG.md
+++ b/docs/CHANGELOG.md
@@ -4,6 +4,12 @@
Newest first. `docs/PROGRESS.md` is the source of truth for *why* a change was made;
this is the *what*, and it is what Settings → About shows as “What's new”.
+## 2026-09-17
+
+**Fixed**
+
+- `managed-apps` support Hermes without systemd
+
## 2026-09-16
**Added**
diff --git a/lib/managed-apps/catalog.test.ts b/lib/managed-apps/catalog.test.ts
index 6fd73e4a..4a9978de 100644
--- a/lib/managed-apps/catalog.test.ts
+++ b/lib/managed-apps/catalog.test.ts
@@ -25,6 +25,7 @@ describe("managed app catalog", () => {
const hermes = getManagedAppDefinition("hermes");
const openclaw = getManagedAppDefinition("openclaw");
expect(hermes.serviceNames).not.toEqual(openclaw.serviceNames);
+ expect(hermes.healthPath).toBe("/api/health");
});
it("keeps 9Router loopback-only unless public exposure is explicitly enabled", () => {
const source = readFileSync(new URL("../../scripts/managed-app-9router", import.meta.url), "utf8");
diff --git a/lib/managed-apps/catalog.ts b/lib/managed-apps/catalog.ts
index 6bc609a8..d908c07c 100644
--- a/lib/managed-apps/catalog.ts
+++ b/lib/managed-apps/catalog.ts
@@ -27,6 +27,7 @@ const definitions = {
serviceNames: ["hermes-dashboard.service", "hermes-gateway.service", "hermes.service"],
containerNames: ["hermes", "hermes-dashboard"],
dashboardUrl: process.env.HERMES_DASHBOARD_URL ?? "http://127.0.0.1:9119",
+ healthPath: "/api/health",
stateDirName: ".hermes",
homeDir: expandHome(process.env.HERMES_HOME),
gradient: "linear-gradient(160deg,#8b5cf6,#4f46e5)",
diff --git a/lib/managed-apps/docker.test.ts b/lib/managed-apps/docker.test.ts
new file mode 100644
index 00000000..a6d70b79
--- /dev/null
+++ b/lib/managed-apps/docker.test.ts
@@ -0,0 +1,47 @@
+import { beforeEach, describe, expect, it, vi } from "vitest";
+
+vi.mock("server-only", () => ({}));
+vi.mock("./runner", () => ({
+ commandExists: vi.fn(),
+ runProgram: vi.fn(),
+}));
+
+const { commandExists, runProgram } = await import("./runner");
+const { dockerUsable, runDocker } = await import("./docker");
+const ok = (stdout = "") => ({ code: 0, stdout, stderr: "" });
+const fail = (stderr = "denied") => ({ code: 1, stdout: "", stderr });
+
+beforeEach(() => {
+ vi.mocked(commandExists).mockReset().mockResolvedValue(true);
+ vi.mocked(runProgram).mockReset();
+});
+
+describe("managed-app Docker runtime", () => {
+ it("uses bare Docker when the service user can reach the daemon", async () => {
+ vi.mocked(runProgram).mockResolvedValue(ok("27.0"));
+ await expect(dockerUsable()).resolves.toBe(true);
+ await runDocker(["ps", "-a"]);
+ expect(vi.mocked(runProgram).mock.calls.some(([cmd, args]) => cmd === "docker" && args[0] === "ps")).toBe(true);
+ expect(vi.mocked(runProgram).mock.calls.some(([cmd]) => cmd === "sudo")).toBe(false);
+ });
+
+ it("falls back to passwordless sudo without putting a shell in the path", async () => {
+ vi.mocked(runProgram).mockImplementation(async (cmd, args) => {
+ if (cmd === "docker" && args[0] === "version") return fail("permission denied");
+ if (cmd === "sudo" && args[0] === "-n" && args[1] === "docker") return ok("27.0");
+ return fail("unexpected");
+ });
+ await expect(dockerUsable()).resolves.toBe(true);
+ const result = await runDocker(["ps", "-a", "--format", "{{.Names}}"]);
+ expect(result.code).toBe(0);
+ expect(vi.mocked(runProgram).mock.calls.some(([cmd, args]) =>
+ cmd === "sudo" && args.slice(0, 3).join(" ") === "-n docker ps",
+ )).toBe(true);
+ });
+
+ it("fails closed when neither direct nor sudo Docker can reach the daemon", async () => {
+ vi.mocked(runProgram).mockResolvedValue(fail());
+ await expect(dockerUsable()).resolves.toBe(false);
+ await expect(runDocker(["ps"])).resolves.toMatchObject({ code: 127 });
+ });
+});
diff --git a/lib/managed-apps/docker.ts b/lib/managed-apps/docker.ts
new file mode 100644
index 00000000..3802aeac
--- /dev/null
+++ b/lib/managed-apps/docker.ts
@@ -0,0 +1,30 @@
+import "server-only";
+import { commandExists, runProgram, type ProgramResult } from "./runner";
+
+type DockerRunner = { command: string; prefix: readonly string[] };
+
+/** Resolve a Docker client that can actually reach the daemon. */
+async function resolveDockerRunner(): Promise<DockerRunner | null> {
+ if (!(await commandExists("docker"))) return null;
+ const probe = ["version", "--format", "{{.Server.Version}}"] as const;
+ const direct = await runProgram("docker", probe, 5_000);
+ if (direct.code === 0) return { command: "docker", prefix: [] };
+ const sudo = await runProgram("sudo", ["-n", "docker", ...probe], 5_000);
+ if (sudo.code === 0) return { command: "sudo", prefix: ["-n", "docker"] };
+ return null;
+}
+
+export async function dockerUsable(): Promise<boolean> {
+ return (await resolveDockerRunner()) !== null;
+}
+
+export async function runDocker(args: readonly string[], timeout = 30_000): Promise<ProgramResult> {
+ const runner = await resolveDockerRunner();
+ if (!runner) return { code: 127, stdout: "", stderr: "docker daemon unavailable to the MSO service user" };
+ return runProgram(runner.command, [...runner.prefix, ...args], timeout);
+}
+
+export async function requireDocker(args: readonly string[], timeout = 30_000): Promise<void> {
+ const result = await runDocker(args, timeout);
+ if (result.code !== 0) throw new Error("managed application Docker operation failed");
+}
diff --git a/lib/managed-apps/manager.ts b/lib/managed-apps/manager.ts
index ece4d68e..44ad8c8a 100644
--- a/lib/managed-apps/manager.ts
+++ b/lib/managed-apps/manager.ts
@@ -2,9 +2,10 @@ import "server-only";
import os from "node:os";
import { createBackup } from "./backups";
import { getManagedAppDefinition, listManagedAppDefinitions } from "./catalog";
+import { dockerUsable, requireDocker, runDocker } from "./docker";
import { acquireOperation, activeOperation, releaseOperation } from "./lock";
import { redact } from "./redact";
-import { commandExists, requireProgram, resolveCommand, runProgram } from "./runner";
+import { commandExists, resolveCommand, runProgram } from "./runner";
import { userBusEnv, userBusUnavailable } from "./user-bus";
import type { ManagedAppAction, ManagedAppDefinition, ManagedAppId, ManagedAppLogs, ManagedAppView } from "./types";
@@ -44,8 +45,8 @@ async function detect(definition: ManagedAppDefinition): Promise<Installation> {
for (const serviceName of definition.serviceNames) {
if (await systemdState(serviceName) !== "missing") return { type: "systemd", serviceName };
}
- if (await commandExists("docker")) {
- const result = await runProgram("docker", ["ps", "-a", "--format", "{{.Names}}"], 10_000);
+ if (await dockerUsable()) {
+ const result = await runDocker(["ps", "-a", "--format", "{{.Names}}"], 10_000);
const names = new Set(result.stdout.split(/\r?\n/).map((name) => name.trim()));
const containerName = definition.containerNames.find((name) => names.has(name));
if (containerName) return { type: "docker", containerName };
@@ -57,7 +58,7 @@ async function detect(definition: ManagedAppDefinition): Promise<Installation> {
async function running(installation: Installation): Promise<boolean> {
if (installation.type === "systemd" && installation.serviceName) return (await systemdState(installation.serviceName)) === "active";
if (installation.type === "docker" && installation.containerName) {
- const result = await runProgram("docker", ["inspect", "--format", "{{.State.Running}}", installation.containerName], 10_000);
+ const result = await runDocker(["inspect", "--format", "{{.State.Running}}", installation.containerName], 10_000);
return result.code === 0 && result.stdout.trim() === "true";
}
return false;
@@ -156,6 +157,7 @@ export async function getManagedApp(id: ManagedAppId): Promise<ManagedAppView> {
: isRunning
? "running"
: "stopped";
+ const dockerFallbackAvailable = id === "hermes" && installation.type === "not-installed" && await dockerUsable();
return {
id,
name: definition.name,
@@ -172,7 +174,9 @@ 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()
- ? "MSO cannot reach this user's systemd bus, so it cannot see user services — this app may in fact be installed. Run `loginctl enable-linger` for the user, and set XDG_RUNTIME_DIR=/run/user/<uid> in mso.service (a drop-in under /etc/systemd/system/mso.service.d/)."
+ ? dockerFallbackAvailable
+ ? 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,
};
}
@@ -198,7 +202,7 @@ async function runLifecycle(installation: Installation, action: "start" | "stop"
throw new Error(`systemctl ${action} ${installation.serviceName} failed: ${lastError.slice(0, 300)}`);
}
if (installation.type === "docker" && installation.containerName) {
- await requireProgram("docker", [action, installation.containerName], 30_000);
+ await requireDocker([action, installation.containerName], 30_000);
return;
}
throw new Error("operation unsupported for detected installation type");
@@ -231,7 +235,7 @@ export async function getManagedAppLogs(id: ManagedAppId): Promise<ManagedAppLog
result = await runProgram("journalctl", ["--user", "-u", installation.serviceName, "-n", "100", "--no-pager", "-o", "short-iso"], 15_000);
if (result.code !== 0) result = await runProgram("journalctl", ["-u", installation.serviceName, "-n", "100", "--no-pager", "-o", "short-iso"], 15_000);
} else if (installation.type === "docker" && installation.containerName) {
- result = await runProgram("docker", ["logs", "--tail", "100", installation.containerName], 15_000);
+ result = await runDocker(["logs", "--tail", "100", installation.containerName], 15_000);
}
if (!result || result.code !== 0) return { available: false, entries: [] };
return { available: true, entries: `${result.stdout}\n${result.stderr}`.split(/\r?\n/).filter(Boolean).slice(-100).map(redact) };
diff --git a/lib/security/managed-app-supply-chain.test.ts b/lib/security/managed-app-supply-chain.test.ts
index 67a64aac..997d6306 100644
--- a/lib/security/managed-app-supply-chain.test.ts
+++ b/lib/security/managed-app-supply-chain.test.ts
@@ -15,6 +15,7 @@ describe("managed-app immutable artifact contract", () => {
expect(lock).toMatch(/HERMES_INSTALLER_TAG='v[^']+'/);
expect(lock).toMatch(/HERMES_INSTALLER_COMMIT='[0-9a-f]{40}'/);
expect(lock).toMatch(/HERMES_INSTALLER_SHA256='[0-9a-f]{64}'/);
+ expect(lock).toMatch(/HERMES_IMAGE_REF='nousresearch\/hermes-agent@sha256:[0-9a-f]{64}'/);
expect(lock).toMatch(/OPENCLAW_VERSION='[^']+'/);
expect(lock).toMatch(/OPENCLAW_TARBALL_SHA512='[0-9a-f]{128}'/);
expect(lock).toMatch(/NINE_ROUTER_IMAGE_REF='[^']+@sha256:[0-9a-f]{64}'/);
@@ -30,6 +31,14 @@ describe("managed-app immutable artifact contract", () => {
expect(executable).not.toMatch(/curl[^\n]+\|\s*(?:ba)?sh/);
});
+ it("pins the Hermes Docker fallback and never uses a mutable image tag", () => {
+ const script = source(INSTALL);
+ expect(script).toContain('"$HERMES_IMAGE_REF" gateway run');
+ expect(script).toContain("HERMES_DASHBOARD_HOST=127.0.0.1");
+ expect(script).toContain("--restart unless-stopped");
+ expect(script).not.toContain("nousresearch/hermes-agent:latest");
+ });
+
it("verifies an exact OpenClaw tarball before lifecycle scripts can run", () => {
const script = source(INSTALL);
expect(script).toContain('npm pack "openclaw@$OPENCLAW_VERSION"');
diff --git a/scripts/managed-app-install b/scripts/managed-app-install
index 25384b3a..4ad49db3 100755
--- a/scripts/managed-app-install
+++ b/scripts/managed-app-install
@@ -33,6 +33,7 @@ validate_artifact_lock() {
[[ "$HERMES_INSTALLER_URL" == "https://raw.githubusercontent.com/NousResearch/hermes-agent/$HERMES_INSTALLER_TAG/scripts/install.sh" ]] || return 1
[[ "$HERMES_INSTALLER_COMMIT" =~ ^[0-9a-f]{40}$ ]] || return 1
[[ "$HERMES_INSTALLER_SHA256" =~ ^[0-9a-f]{64}$ ]] || return 1
+ [[ "$HERMES_IMAGE_REF" =~ ^nousresearch/hermes-agent@sha256:[0-9a-f]{64}$ ]] || return 1
[[ "$OPENCLAW_VERSION" =~ ^[0-9][0-9A-Za-z.-]*$ ]] || return 1
[[ "$OPENCLAW_TARBALL_SHA512" =~ ^[0-9a-f]{128}$ ]] || return 1
}
@@ -95,35 +96,143 @@ ensure_user_bus() {
return 1
}
+
+# Hosted/systemd-less installs may expose Docker only through passwordless sudo.
+docker_cli() {
+ if docker version --format '{{.Server.Version}}' >/dev/null 2>&1; then
+ DOCKER=(docker)
+ return 0
+ fi
+ if sudo -n docker version --format '{{.Server.Version}}' >/dev/null 2>&1; then
+ DOCKER=(sudo -n docker)
+ return 0
+ fi
+ return 1
+}
+
+HERMES_RUNTIME=native
+
# Checked HERE, before ~20 minutes of downloading and compiling, because the last
# step is the most expensive place to discover a missing environment variable.
if command -v systemctl >/dev/null 2>&1; then
if ensure_user_bus; then
log "user systemd bus: ${XDG_RUNTIME_DIR}/bus"
+ elif [ "$APP" = "hermes" ] && docker_cli; then
+ HERMES_RUNTIME=docker
+ log "user systemd unavailable; Hermes will use its pinned Docker runtime"
else
cat >&2 <<MSG
cannot reach the systemd user bus for $(id -un), so $APP's service could not be
installed even if everything else succeeded. Nothing has been changed.
-MSO is probably running as a systemd system unit, which gets no login session and
-therefore no XDG_RUNTIME_DIR. Fix it once, on the host:
-
- sudo loginctl enable-linger $(id -un)
- sudo mkdir -p /etc/systemd/system/mso.service.d
- printf '[Service]\nEnvironment=XDG_RUNTIME_DIR=/run/user/%s\n' "$(id -u)" \\
- | sudo tee /etc/systemd/system/mso.service.d/10-user-bus.conf
- sudo systemctl daemon-reload && sudo systemctl restart mso
-
-Then start this install again.
+On a normal systemd host, enable user linger and give MSO the user's runtime dir.
+On a systemd-less/container host, Hermes can instead use the reviewed Docker
+runtime when Docker is available to the MSO service account.
MSG
exit 1
fi
else
- echo "no systemctl on this host — $APP will be installed without a service" >&2
+ if [ "$APP" = "hermes" ] && docker_cli; then
+ HERMES_RUNTIME=docker
+ log "systemd is unavailable; Hermes will use its pinned Docker runtime"
+ else
+ echo "no usable systemd user bus or Docker runtime for $APP" >&2
+ exit 1
+ fi
fi
# ---------------------------------------------------------------- hermes ----
+hermes_provider_env_name() {
+ case "$PROVIDER" in
+ anthropic) echo ANTHROPIC_API_KEY ;;
+ openai) echo OPENAI_API_KEY ;;
+ openrouter) echo OPENROUTER_API_KEY ;;
+ nous) echo NOUS_API_KEY ;;
+ "") return 1 ;;
+ *) echo "unsupported Hermes provider '$PROVIDER'" >&2; return 2 ;;
+ esac
+}
+
+persist_hermes_provider_key() {
+ [ -n "$KEY" ] || return 0
+ local env_name env_file tmp
+ env_name="$(hermes_provider_env_name)" || return 1
+ case "$KEY" in
+ *$'\n'*|*$'\r'*) echo "Hermes provider key contains a control character" >&2; return 1 ;;
+ esac
+ mkdir -p "$HOME/.hermes"
+ env_file="$HOME/.hermes/.env"
+ tmp="$(mktemp "$HOME/.hermes/.env.mso.XXXXXX")"
+ if [ -f "$env_file" ]; then
+ grep -v "^${env_name}=" "$env_file" >"$tmp" || true
+ fi
+ printf '%s=%s\n' "$env_name" "$KEY" >>"$tmp"
+ chmod 600 "$tmp"
+ mv "$tmp" "$env_file"
+}
+
+install_hermes_docker() {
+ docker_cli || { echo "Docker is unavailable to $(id -un)" >&2; return 1; }
+ mkdir -p "$HOME/.hermes"
+
+ if "${DOCKER[@]}" container inspect hermes >/dev/null 2>&1; then
+ local configured_image
+ configured_image="$("${DOCKER[@]}" inspect --format '{{.Config.Image}}' hermes 2>/dev/null || true)"
+ if [ "$configured_image" != "$HERMES_IMAGE_REF" ]; then
+ echo "a container named 'hermes' already exists with a different image; refusing to replace it" >&2
+ return 1
+ fi
+ log "Hermes container already exists; starting the reviewed image"
+ "${DOCKER[@]}" start hermes >/dev/null
+ else
+ log "pulling pinned Hermes image ($HERMES_INSTALLER_TAG)"
+ "${DOCKER[@]}" pull "$HERMES_IMAGE_REF"
+
+ persist_hermes_provider_key
+
+ log "configuring Hermes in the persistent data volume"
+ "${DOCKER[@]}" run --rm --network host \
+ -v "$HOME/.hermes:/opt/data" \
+ -e "HERMES_UID=$(id -u)" -e "HERMES_GID=$(id -g)" \
+ "$HERMES_IMAGE_REF" setup --non-interactive
+
+ log "starting Hermes gateway + dashboard on loopback"
+ "${DOCKER[@]}" run -d \
+ --name hermes \
+ --restart unless-stopped \
+ --network host \
+ -v "$HOME/.hermes:/opt/data" \
+ -e "HERMES_UID=$(id -u)" \
+ -e "HERMES_GID=$(id -g)" \
+ -e HERMES_DASHBOARD=1 \
+ -e HERMES_DASHBOARD_HOST=127.0.0.1 \
+ "$HERMES_IMAGE_REF" gateway run >/dev/null
+ fi
+
+ local i running
+ for i in $(seq 1 90); do
+ if curl -fsS -o /dev/null --max-time 3 "http://127.0.0.1:${HERMES_DASHBOARD_PORT:-9119}/api/health"; then
+ log "Hermes Docker dashboard is answering on ${HERMES_DASHBOARD_PORT:-9119}"
+ return 0
+ fi
+ running="$("${DOCKER[@]}" inspect --format '{{.State.Running}}' hermes 2>/dev/null || true)"
+ if [ "$running" != "true" ]; then
+ echo "Hermes container exited before the dashboard became healthy" >&2
+ "${DOCKER[@]}" logs --tail 80 hermes >&2 || true
+ return 1
+ fi
+ sleep 2
+ done
+ echo "Hermes container is running but /api/health did not answer within 180s" >&2
+ "${DOCKER[@]}" logs --tail 80 hermes >&2 || true
+ return 1
+}
+
install_hermes() {
+ if [ "$HERMES_RUNTIME" = docker ]; then
+ install_hermes_docker
+ return
+ fi
local tmp
tmp="$(mktemp -d)"
trap 'rm -rf "$tmp"' RETURN
@@ -173,6 +282,7 @@ install_hermes() {
fi
hermes_cmd
+ persist_hermes_provider_key
log "configuring from the environment"
# `setup --non-interactive` is documented as "use defaults/env vars", and Hermes
# reads ANTHROPIC_API_KEY / OPENAI_API_KEY / OPENROUTER_API_KEY / NOUS_API_KEY —
diff --git a/security/managed-app-artifacts.env b/security/managed-app-artifacts.env
index 961bec92..a92a96e1 100644
--- a/security/managed-app-artifacts.env
+++ b/security/managed-app-artifacts.env
@@ -5,6 +5,7 @@ HERMES_INSTALLER_TAG='v2026.8.27'
HERMES_INSTALLER_COMMIT='5fc308a70719a83cccdbba4c0e39c23f5a8239d5'
HERMES_INSTALLER_URL='https://raw.githubusercontent.com/NousResearch/hermes-agent/v2026.8.27/scripts/install.sh'
HERMES_INSTALLER_SHA256='c0380bc1f78d3d662a77663ce20cc17e14cbc4bec35e61ab7a33bac5f3afed2d'
+HERMES_IMAGE_REF='nousresearch/hermes-agent@sha256:e0df6adebddf29b91112aefc999d4aaf6846c9eb544faca5672a16a13590ff79'
OPENCLAW_VERSION='2026.7.1-2'
OPENCLAW_TARBALL_SHA512='c9c177c8f71b8cde9b50f79a531e8c87abf37b58505a80f7093ff059c983edaf316871c745468095aabe945c4c1dfd6cb0480e0d50308e5cd8aa9dadc24619ee'