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
fix(managed-apps): support Hermes without systemd
Abdurrahman Fakhruld3918cf6bb1d
diff --git a/docs/CHANGELOG.md b/docs/CHANGELOG.mdindex 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.tsindex 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.tsindex 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsindex 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<ManagedAppLogresult = 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.tsindex 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-installindex 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; thenif ensure_user_bus; thenlog "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"elsecat >&2 <<MSGcannot reach the systemd user bus for $(id -un), so $APP's service could not beinstalled 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.MSGexit 1fielse- 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+ fifi# ---------------------------------------------------------------- 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+ filocal tmptmp="$(mktemp -d)"trap 'rm -rf "$tmp"' RETURN@@ -173,6 +282,7 @@ install_hermes() {fihermes_cmd+ persist_hermes_provider_keylog "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.envindex 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'