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 os from "node:os";
import { managedAppHealth } from "./health";
import { createBackup } from "./backups";
import { getManagedAppDefinition, listManagedAppDefinitions } from "./catalog";
import { dockerUsable, requireDocker, runDocker } from "./docker";
import { provisionDomainAfterStart, readManagedDomainView } from "./domain-lifecycle";
import { acquireOperation, activeOperation, releaseOperation, withManagedAppOperationLease } from "./lock";
import { redact } from "./redact";
import { listJobRecords } from "./job-store";
import { detectOrca, detectOwnedOrcaForStop, invalidateOrcaIntegrityCache, orcaUnknownDiagnostic, ORCA_SERVICE, type ManagedInstallation } from "./orca-installation";
import { commandExists, resolveCommand, runProgram } from "./runner";
import { managedRunState, running, systemdState } from "./service-state";
import { userBusEnv, userBusUnavailable } from "./user-bus";
import type { ManagedAppAction, ManagedAppDefinition, ManagedAppId, ManagedAppLogs, ManagedAppView } from "./types";
async function detect(definition: ManagedAppDefinition, strict = false): Promise<ManagedInstallation> {
// Orca is MSO-owned state: only the exact owned USER unit plus a verified
// install receipt counts, in a single scope. The generic path below cannot
// prove either, so it must never run for Orca.
// Strict check must fail closed when Orca is not installed or has ambiguous/stale state,
// as absence cannot be proven without an owned stopped unit.
if (definition.id === "orca") {
const result = await detectOrca({ adapterPath: definition.command, freshVerification: strict });
if (strict && result.type === "not-installed") {
throw new Error(result.diagnostic ?? "Cannot confirm Orca is stopped: install state cannot prove absence");
}
return result;
}
const serviceNames: string[] = [];
for (const serviceName of definition.serviceNames) {
if (await systemdState(serviceName, strict) !== "missing") serviceNames.push(serviceName);
}
let containerNames: string[] = [];
if (await dockerUsable()) {
const result = await runDocker(["ps", "-a", "--format", "{{.Names}}"], 10_000);
if (result.code !== 0) throw new Error("Cannot confirm managed-app container inventory");
const names = new Set(result.stdout.split(/\r?\n/).map((name) => name.trim()));
containerNames = definition.containerNames.filter((name) => names.has(name));
} else if (strict && await commandExists("docker")) throw new Error("Cannot confirm managed-app Docker state");
if (serviceNames.length || containerNames.length) return { type: serviceNames.length ? "systemd" : "docker", ...(serviceNames.length ? { serviceName: serviceNames[0], serviceNames } : {}), ...(containerNames.length ? { containerName: containerNames[0], containerNames } : {}) };
if (definition.commandProvesInstall !== false && await commandExists(definition.command)) return { type: "package" };
return { type: "not-installed" };
}
/** Globally-routable IPv4 only. Private/CGNAT/link-local addresses are useful for
* MSO's internal proxy but are not the "works without a domain" address a user
* can open from their own browser. No external IP-discovery service is called. */
function isPublicIpv4(address: string): boolean {
const parts = address.split(".").map(Number);
if (parts.length !== 4 || parts.some((part) => !Number.isInteger(part) || part < 0 || part > 255)) return false;
const [a, b] = parts;
if (a === 0 || a === 10 || a === 127 || a >= 224) return false;
if (a === 100 && b >= 64 && b <= 127) return false; // RFC 6598 CGNAT
if (a === 169 && b === 254) return false;
if (a === 172 && b >= 16 && b <= 31) return false;
if (a === 192 && b === 168) return false;
return true;
}
export function hostPublicIpv4(): string | null {
for (const addresses of Object.values(os.networkInterfaces())) {
for (const address of addresses ?? []) {
if (address.family === "IPv4" && !address.internal && isPublicIpv4(address.address)) return address.address;
}
}
return null;
}
function directDashboardUrl(definition: ManagedAppDefinition): string | null {
const configured = definition.publicUrl?.trim();
if (configured) {
try {
const url = new URL(configured);
if ((url.protocol === "https:" || url.protocol === "http:") && !url.username && !url.password) {
return configured.replace(/\/$/, "");
}
} catch {
// Bad operator config is not an app-health failure; fall through to the IP path.
}
}
if (!definition.publicPort) return null;
const address = hostPublicIpv4();
return address ? `http://${address}:${definition.publicPort}` : null;
}
// `--version` forks the app's own binary, which is not free (hermes: ~0.44 s of CPU
// per call on this host) — and the Managed Apps panel re-polls every 10 s, for a
// string that only changes on upgrade. Cached per app id; performManagedAppAction
// drops the entry, since an install/restart is the only thing that can move it.
const VERSION_TTL_MS = 60_000;
const versionCache = new Map<ManagedAppId, { value: string | null; at: number }>();
async function version(definition: ManagedAppDefinition): Promise<string | null> {
const hit = versionCache.get(definition.id);
if (hit && Date.now() - hit.at < VERSION_TTL_MS) return hit.value;
let value: string | null = null;
// Resolved to a path, not spawned by bare name: under systemd the unit's PATH
// does not contain ~/.local/bin, where both upstream CLIs install themselves.
const program = await resolveCommand(definition.command);
if (program) {
const result = await runProgram(program, ["--version"], 10_000);
value = result.code === 0 ? result.stdout.trim().split(/\r?\n/)[0]?.slice(0, 160) || null : null;
}
versionCache.set(definition.id, { value, at: Date.now() });
return value;
}
function actionsFor(installation: ManagedInstallation): ManagedAppAction[] {
if (installation.type === "systemd" || installation.type === "docker") return ["start", "stop", "restart", "backup"];
if (installation.type === "package") return ["backup"];
return [];
}
export async function getManagedApp(id: ManagedAppId): Promise<ManagedAppView> {
const definition = getManagedAppDefinition(id);
const installation = await detect(definition);
let runState = await managedRunState(installation);
let stopOnlyOwned = false;
if (id === "orca" && installation.type === "not-installed") {
const stopInstall = await detectOwnedOrcaForStop();
if (stopInstall.owned) {
stopOnlyOwned = true;
runState = await managedRunState(stopInstall);
}
}
const isRunning = runState === "running";
const isHealthy = isRunning && !stopOnlyOwned ? await managedAppHealth(definition) : null;
const operation = activeOperation(id);
const state = operation === "start"
? "starting"
: installation.type === "not-installed" && !stopOnlyOwned
? "not-installed"
: runState === "unknown" ? "error" : isHealthy === false ? "unhealthy" : isRunning ? "running" : "stopped";
const dockerInstallAvailable = definition.installBackends.includes("docker") && installation.type === "not-installed" && await dockerUsable();
const domainView = await readManagedDomainView(id);
return {
id,
name: definition.name,
description: definition.description,
installed: installation.type !== "not-installed",
installationType: installation.type,
state,
healthy: isHealthy,
version: await version(definition),
dashboardAvailable: isRunning && isHealthy !== false && !stopOnlyOwned,
publicDashboardUrl: domainView.domain?.phase === "ready" ? `https://${domainView.domain.hostname}` : directDashboardUrl(definition),
...domainView,
supportedActions: stopOnlyOwned ? ["stop"] : actionsFor(installation),
// Only ever attached to a NEGATIVE reading. An app detected as present has
// been seen, and nothing about the bus can make that observation wrong.
diagnostic:
installation.diagnostic ??
(runState === "unknown" && (installation.serviceName ?? (stopOnlyOwned ? ORCA_SERVICE : undefined))
? orcaUnknownDiagnostic(installation.serviceName ?? ORCA_SERVICE)
: installation.type === "not-installed" && userBusUnavailable()
? 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),
};
}
export async function listManagedApps(): Promise<ManagedAppView[]> {
const views: ManagedAppView[] = [];
for (const definition of listManagedAppDefinitions()) views.push(await getManagedApp(definition.id));
return views;
}
export async function assertManagedAppStopped(id: ManagedAppId): Promise<void> {
if (await running(await detect(getManagedAppDefinition(id), true), true)) throw new Error("Cannot confirm app is stopped; stop all app services before backup or restore");
}
async function runLifecycle(installation: ManagedInstallation, action: "start" | "stop" | "restart"): Promise<void> {
// Owned Orca runs as a USER unit under MSO's control. Act on exactly that unit
// and never fall through to a same-name system unit.
if (installation.owned && installation.serviceName) {
const result = await runProgram("systemctl", ["--user", action, installation.serviceName], 30_000, userBusEnv());
if (result.code !== 0) {
const detail = result.stderr.trim() || result.stdout.trim() || `systemctl exited ${result.code}`;
throw new Error(`systemctl --user ${action} ${installation.serviceName} failed: ${detail.slice(0, 300)}`);
}
return;
}
if (installation.serviceNames || installation.containerNames) {
for (const serviceName of installation.serviceNames ?? []) await runLifecycle({ type: "systemd", serviceName }, action);
for (const containerName of installation.containerNames ?? []) await runLifecycle({ type: "docker", containerName }, action);
if (action === "stop" && await running(installation)) throw new Error("A managed-app service is still active after stop");
return;
}
if (installation.type === "systemd" && installation.serviceName) {
let lastError = "";
let succeeded = false;
for (const args of [["--user", action, installation.serviceName], [action, installation.serviceName]]) {
const result = await runProgram("systemctl", args, 30_000, args[0] === "--user" ? userBusEnv() : undefined);
if (result.code === 0) succeeded = true;
lastError = result.stderr.trim() || result.stdout.trim() || `systemctl exited ${result.code}`;
}
if (succeeded) return;
// Falling through to the generic throw below reported every one of these as
// "operation unsupported for detected installation type" — served as a 409,
// and flatly untrue: the installation type was detected fine, systemctl just
// refused. An unreachable user bus surfaced as a category error about the app.
throw new Error(`systemctl ${action} ${installation.serviceName} failed: ${lastError.slice(0, 300)}`);
}
if (installation.type === "docker" && installation.containerName) {
await requireDocker([action, installation.containerName], 30_000);
return;
}
throw new Error("operation unsupported for detected installation type");
}
export async function performManagedAppAction(id: ManagedAppId, action: ManagedAppAction): Promise<ManagedAppView> {
await withManagedAppOperationLease(id, async () => {
if ((await listJobRecords(id)).some((job) => job.status === "queued" || job.status === "running")) {
throw new Error("another operation is already running");
}
if (!acquireOperation(id, action)) throw new Error("another operation is already running");
try {
const definition = getManagedAppDefinition(id);
const isOrcaStop = id === "orca" && action === "stop";
const installation = isOrcaStop ? await detectOwnedOrcaForStop() : await detect(definition, id === "orca");
if (isOrcaStop ? (!installation.owned || installation.type === "not-installed") : !actionsFor(installation).includes(action)) {
throw new Error(installation.diagnostic ?? "operation unsupported for detected installation type");
}
if (action === "backup") await createBackup(definition, "manual", () => assertManagedAppStopped(id));
else await runLifecycle(installation, action);
} finally {
releaseOperation(id);
versionCache.delete(id);
if (id === "orca") invalidateOrcaIntegrityCache();
}
});
const domain = action === "start" || action === "restart" ? await provisionDomainAfterStart(id) : null;
const view = await getManagedApp(id);
return domain?.domainDiagnostic ? { ...view, domainDiagnostic: domain.domainDiagnostic } : view;
}
export async function getManagedAppLogs(id: ManagedAppId): Promise<ManagedAppLogs> {
const definition = getManagedAppDefinition(id);
const installation = await detect(definition);
let result = null;
if (installation.type === "systemd" && installation.serviceName) {
result = await runProgram("journalctl", ["--user", "-u", installation.serviceName, "-n", "100", "--no-pager", "-o", "short-iso"], 15_000);
// Owned Orca logs are user-scope only: a system fallback could read a foreign unit.
if (result.code !== 0 && !installation.owned) 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 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) };
}