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
import "server-only";
import { promises as fs } from "node:fs";
import path from "node:path";
import { createBackup, isManagedAppBackupId, stateDirFor } from "./backups";
import { getManagedAppDefinition } from "./catalog";
import { startManagedAppJob } from "./jobs";
import { activeOperation } from "./lock";
import { assertManagedAppStopped } from "./manager";
import { restoreManagedAppBackup } from "./restore";
import { resolveCommand, runProgram } from "./runner";
import type { ManagedAppDefinition, ManagedAppId, ManagedAppJob } from "./types";
import { assertChannel, updateAdapter, UNINSTALL_PREVIEW_FLAG } from "./update-cli";
import type { ManagedAppBackup, ManagedAppUpdateOptions, ManagedAppUpdateStatus } from "./update-types";
/** OpenClaw's own per-STEP timeout is 1800 s and a run has several steps, so a
* 30-minute wall clock would kill a healthy update mid-step. An hour is the
* job layer's ceiling; upstream's own step timeout fires long before it. */
const UPDATE_TIMEOUT_MS = 3_600_000;
const UNINSTALL_TIMEOUT_MS = 900_000;
/** A check spawns the app's CLI and, for Hermes, git-fetches twice. Cheap to
* cache, expensive to poll. */
const CHECK_CACHE_MS = 60_000;
const cache = new Map<ManagedAppId, ManagedAppUpdateStatus>();
function safeCapabilities(id: ManagedAppId, capabilities = updateAdapter(id).capabilities) {
if (id === "9router") return capabilities;
// Hermes/OpenClaw upstream update commands fetch mutable branch/channel/tag
// content and execute it before MSO can verify repository-owned bytes. Until
// a reviewed release artifact + digest is committed, discovery stays enabled
// but apply/channel/dry-run update execution fails closed.
return { ...capabilities, apply: false, dryRun: false, channel: false };
}
function assertVerifiedUpdatePath(id: ManagedAppId): void {
if (id !== "9router") {
throw new Error(`${id} automated update is disabled until a reviewed immutable artifact target and digest are committed`);
}
}
/** Resolve the exact CLI or fail before creating a job. */
async function resolveProgram(command: string): Promise<string> {
// Share detection's fallback for user-local CLIs outside systemd PATH.
const resolved = await resolveCommand(command);
if (!resolved || !path.isAbsolute(resolved)) throw new Error(`${command} is not installed`);
return resolved;
}
const message = (error: unknown): string => (error instanceof Error ? error.message : String(error));
function unavailable(id: ManagedAppId, error: string): ManagedAppUpdateStatus {
const { capabilities } = updateAdapter(id);
return {
applicationId: id,
currentVersion: null,
latestVersion: null,
updateAvailable: null,
detail: null,
channel: { value: null, kind: null, available: [], switchable: false, reason: null },
installKind: null,
// File-based rollback survives a missing CLI; execution controls do not.
capabilities: { ...safeCapabilities(id, capabilities), check: false, apply: false, dryRun: false, channel: false, uninstall: false, rollback: capabilities.rollback ? true : false },
checkedAt: new Date().toISOString(),
error,
};
}
/** What a READ of the status serves: the last probe, or an empty shell when this
* server has not probed since it started. It never spawns anything — probing is
* a POST precisely because it runs the app's CLI and, for Hermes, git-fetches
* the operator's checkout twice. The shell still declares what the app
* supports, so the panel can render controls; only the FACTS are missing, and
* `checkedAt: null` is how it knows to ask for a probe. */
export function cachedUpdateStatus(id: ManagedAppId): ManagedAppUpdateStatus {
const cached = cache.get(id);
if (cached) return cached;
return {
applicationId: id, currentVersion: null, latestVersion: null, updateAvailable: null, detail: null,
channel: { value: null, kind: null, available: [], switchable: false, reason: null },
installKind: null, capabilities: safeCapabilities(id), checkedAt: null, error: null,
};
}
/** Normalised update status for one app. Cached for a minute; `force` is what
* the explicit "Check for updates" button sends. */
export async function checkUpdate(id: ManagedAppId, force = false): Promise<ManagedAppUpdateStatus> {
const cached = cache.get(id);
// A cache entry always carries a stamp; `?? ""` parses to NaN, so an entry
// that somehow does not is re-probed instead of being served forever.
if (cached && !force && Date.now() - Date.parse(cached.checkedAt ?? "") < CHECK_CACHE_MS) return cached;
// Probing runs the app's own CLI, and Hermes' check git-fetches the very
// checkout a running update job is rebasing. Never race the job for it.
const busy = activeOperation(id);
if (busy) return cached ?? unavailable(id, `an operation is already running (${busy})`);
const adapter = updateAdapter(id);
let status: ManagedAppUpdateStatus;
try {
const probe = await adapter.probe(await resolveProgram(getManagedAppDefinition(id).command));
status = { applicationId: id, ...probe, capabilities: safeCapabilities(id, adapter.capabilities), checkedAt: new Date().toISOString() };
} catch (error) {
status = unavailable(id, message(error));
}
cache.set(id, status);
return status;
}
const exists = (target: string): Promise<boolean> =>
fs.lstat(target).then(() => true, () => false);
/** The mandatory pre-flight snapshot. It runs inside the job, inside the lock,
* BEFORE anything spawns — and a throw here ends the job `failed` with nothing
* executed, which is the whole mechanism for "a failed backup aborts the
* update" (jobs.ts `prepare`). Null = there was nothing to snapshot. */
async function snapshot(definition: ManagedAppDefinition, reason: ManagedAppBackup["reason"], append: (text: string) => void): Promise<ManagedAppBackup | null> {
const source = stateDirFor(definition);
append(`[mso] ${reason} backup of ${source}\n`);
// UNINSTALL only: a missing state dir left an app whose data was already
// removed by hand permanently un-uninstallable — the job died here and the
// uninstall never ran, with no way out through the UI. There is nothing left to
// protect, so say so and continue. An UPDATE keeps failing closed: its state
// dir is also the install (Hermes' is a git checkout), so its absence means
// something is wrong that an update should not paper over.
if (reason === "pre-uninstall" && !(await exists(source))) {
append(`[mso] nothing to back up - ${source} does not exist\n`);
return null;
}
let backup: ManagedAppBackup;
try {
backup = await createBackup(definition, reason, () => assertManagedAppStopped(definition.id));
} catch (error) {
throw new Error(`${reason} backup failed, nothing was run: ${message(error)}`);
}
const mb = backup.bytes === null ? "?" : (backup.bytes / 1024 / 1024).toFixed(1);
append(`[mso] backup ${backup.id} - ${backup.files ?? "?"} files, ${mb} MB\n`);
// Said out loud every time, because it is what makes this a STATE snapshot
// rather than an install image: restoring it will not rebuild a git checkout
// or a node_modules tree.
append(`[mso] not in the backup (and not restorable from it): ${backup.skipped.dirNames.join(", ")}\n`);
return backup;
}
/** Update, or preview one. `dryRun` skips the backup on purpose: a preview
* writes nothing, and copying 366 MB to predict a no-op is theatre. */
export async function startUpdate(id: ManagedAppId, options: ManagedAppUpdateOptions = {}): Promise<ManagedAppJob> {
assertVerifiedUpdatePath(id);
const definition = getManagedAppDefinition(id);
const argv = updateAdapter(id).updateArgv(await resolveProgram(definition.command), options);
return startManagedAppJob({
applicationId: id,
kind: "update",
argv,
timeoutMs: UPDATE_TIMEOUT_MS,
prepare: options.dryRun ? undefined : (append) => snapshot(definition, "pre-update", append).then(() => undefined),
});
}
/** A channel switch executes an update, so it needs the same immutable target. */
export async function setChannel(id: ManagedAppId, channel: string): Promise<ManagedAppJob> {
const adapter = updateAdapter(id);
if (!adapter.capabilities.channel) throw new Error(`channel switching is not supported for ${id}`);
assertVerifiedUpdatePath(id);
return startUpdate(id, { channel: assertChannel(channel) });
}
/** A preview is the ONE flow that skips the mandatory pre-flight backup, and
* both CLIs refuse a headless uninstall — preview included — unless a
* confirmation flag rides along (proof in update-cli.ts). So whether the
* installed CLI still honours `--dry-run` is all that stands between "Preview
* removal" and a real, unbacked-up removal. Ask it: `--help` costs ~0.3 s next
* to what it guards, and a refused preview costs nothing at all. */
async function assertPreviewSupported(program: string, id: ManagedAppId): Promise<void> {
const help = await runProgram(program, ["uninstall", "--help"], 10_000);
if (!`${help.stdout}${help.stderr}`.includes(UNINSTALL_PREVIEW_FLAG)) {
throw new Error(`the installed ${id} CLI does not advertise \`uninstall ${UNINSTALL_PREVIEW_FLAG}\`, so previewing a removal is not supported`);
}
}
/** Uninstall. `confirmation` must be the app id, typed by the operator — this
* is the second gate after the session, and the reason a stray POST cannot
* remove an app. */
export async function startUninstall(id: ManagedAppId, confirmation: unknown, dryRun = false): Promise<ManagedAppJob> {
if (confirmation !== id) throw new Error("uninstall confirmation does not match the application id");
const definition = getManagedAppDefinition(id);
const program = await resolveProgram(definition.command);
if (dryRun) await assertPreviewSupported(program, id);
const argv = updateAdapter(id).uninstallArgv(program, dryRun);
return startManagedAppJob({
applicationId: id,
kind: "uninstall",
argv,
timeoutMs: UNINSTALL_TIMEOUT_MS,
prepare: dryRun ? undefined : (append) => snapshot(definition, "pre-uninstall", append).then(() => undefined),
});
}
/** Rollback = restore a snapshot, then optionally pin the version that snapshot
* belongs with — OpenClaw's `--tag` only; Hermes has no pin that survives a
* restore (`UpdateAdapter.pin` is null there). Neither app has a rollback verb
* of its own. One job: the restore is `prepare`, the pin is the argv, so a
* restore that fails never runs the pin. */
export async function startRollback(id: ManagedAppId, backupId: string, pin?: string): Promise<ManagedAppJob> {
if (!isManagedAppBackupId(backupId)) throw new Error("unknown backup");
const adapter = updateAdapter(id);
if (!adapter.capabilities.rollback) throw new Error(`rollback is not supported for ${id}`);
// Refused rather than silently dropped: for Hermes the pin IS a branch switch,
// which auto-stashes the very files the restore just wrote back (update-cli.ts)
// — a rollback that quietly undoes itself and still reports success.
if (pin && !adapter.pin) throw new Error(`pinning a version during a rollback is not supported for ${id}: its pin switches the git checkout, which would stash the restored files`);
if (pin) throw new Error(`pinning during rollback is disabled until ${id} has a reviewed immutable artifact target and digest`);
const argv: string[] = [];
return startManagedAppJob({
applicationId: id,
kind: "restore",
argv,
timeoutMs: UPDATE_TIMEOUT_MS,
prepare: (append) => restoreManagedAppBackup(id, backupId, append).then(() => undefined),
});
}