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 { ownedArtifactSession } from "@/lib/agent/artifact-session";
import { saveSessionArtifact } from "@/lib/agent/artifacts";
import { artifactPaths } from "@/lib/agent/artifact-paths";
import path from "node:path";
import { listDir, readFile, searchFs, usage, statReadableMeta, sha256Text, utf8Bytes } from "@/lib/host/fs-api";
import { stats, processes } from "@/lib/host/system-api";
import { captureMsoScreen } from "@/lib/host/screenshot-api";
import { createTempShare, tempShareUrl } from "@/lib/host/temp-share-api";
import { camoufoxStatus } from "@/lib/camoufox/service";
import { listManagedApps, getManagedAppLogs } from "@/lib/managed-apps/manager";
import { searchSkillMemory } from "@/lib/skills/search";
import { isManagedAppId } from "@/lib/managed-apps/catalog";
import { type McpTool, str, opt, S, PATH_P, READ_ONLY, mcpDirect } from "./tool-kit";
// The read tier: observability with no way to change anything. Everything here is
// answerable without granting a shell, which is the whole point of the tiering —
// "why is hermes down?" should not cost the same trust as `exec_run`.
export const READ_TOOLS: McpTool[] = [
{
name: "fs_list",
description:
"List a directory on the VPS. Returns entries with name and type. Size is reported as 0 for " +
"every entry and is NOT a real size — never conclude a file is empty from it. " +
"USE THIS FIRST to discover paths before reading or writing — guessing a path wastes a call. " +
"Reads are bounded to OS_FS_READ_ROOTS and credential paths (~/.ssh, ~/.mso, cloud tokens) are refused.",
scope: "read",
annotations: READ_ONLY,
inputSchema: S({ ...PATH_P, includeHidden: { type: "boolean", description: "Include dotfiles. Default true." } }, ["path"]),
run: (a) => listDir(str(a, "path"), a.includeHidden !== false),
},
{
name: "fs_read",
description:
"Read a text file on the VPS and return its contents plus UTF-8 byte count and SHA-256. " +
"Use that hash as fs_write.expected_sha256 to avoid overwriting a file changed since inspection. For binary files this will be garbage — " +
"check the extension from fs_list first. NOT for finding a file: use fs_search.",
scope: "read",
annotations: READ_ONLY,
result: { maxTextBytes: 64 * 1024, overflowHint: "Read a narrower file/range through a project-specific function or inspect only the relevant section." },
inputSchema: S(PATH_P, ["path"]),
run: async (a) => {
const content = await readFile(str(a, "path"));
return { path: a.path, content, bytes: utf8Bytes(content), sha256: sha256Text(content) };
},
},
{
name: "fs_stat",
description:
"Get bounded metadata for a file or directory on the VPS (kind, true sizeBytes, mtimeMs, ctimeMs, mode). " +
"Use this for true file size or modification time without reading file contents or launching a shell. " +
"Reads are bounded to OS_FS_READ_ROOTS and credential paths (~/.ssh, ~/.mso, cloud tokens) are refused.",
scope: "read",
annotations: READ_ONLY,
inputSchema: S(PATH_P, ["path"]),
run: (a) => statReadableMeta(str(a, "path")),
},
{
name: "fs_search",
description:
"Find DIRECTORIES whose name contains a fragment, recursively, under a root. Use it to locate a " +
"project folder before fs_list — it is bounded and needs no shell scope, unlike exec_run with find. " +
"It does NOT match file names or file contents; fs_list the directory it returns.",
scope: "read",
annotations: READ_ONLY,
inputSchema: S({
query: { type: "string", description: "Substring matched against directory names." },
root: { type: "string", description: "Where to search from. Defaults to ~/projects." },
}, ["query"]),
run: (a) => searchFs(str(a, "query"), { root: opt(a, "root") }),
},
{
name: "fs_usage",
description: "Disk usage for a path: total, used and free bytes. Use for 'is the VPS full?'.",
scope: "read",
annotations: READ_ONLY,
inputSchema: S(PATH_P, ["path"]),
run: (a) => usage(str(a, "path")),
},
{
name: "sys_stats",
description:
"Live VPS health: CPU load, memory, disk and uptime. Uptime is returned with explicit units as uptimeMs and uptimeSeconds — never interpret either as days. " +
"USE THIS for 'how is the server doing'; it is one cheap call and needs no shell scope.",
scope: "read",
annotations: READ_ONLY,
inputSchema: S({}),
run: async () => {
const { uptime, ...health } = await stats();
return { ...health, uptimeMs: Math.round(uptime), uptimeSeconds: Math.round(uptime / 1000) };
},
},
{
name: "sys_processes",
description: "Top processes by CPU with pid, command, cpu% and memory%. Use to find what is eating the box.",
scope: "read",
annotations: READ_ONLY,
inputSchema: S({}),
run: () => processes(),
},
{
name: "apps_list",
description:
"List the managed applications mso can install and control on this VPS, with install and running state. " +
"This is NOT the mso app list (Files, Terminal, …) — those are UI surfaces with no server state.",
scope: "read",
annotations: READ_ONLY,
inputSchema: S({}),
// `{ apps: [...] }`, not a bare array — GET /api/v1/managed-apps is the authority
// on this shape and `mso mapp list` already prints its envelope. Returning the
// array raw meant one capability answered in two shapes depending on which
// surface asked, which is exactly the drift the parity gate exists to stop.
run: async () => ({ apps: await listManagedApps() }),
},
{
name: "apps_logs",
description:
"Recent log output for a managed application (hermes, openclaw). USE THIS to answer 'why is X " +
"down' — it needs only read scope, where the same question via exec_run would need a full shell. " +
"Call apps_list first for the valid ids and their state.",
scope: "read",
annotations: READ_ONLY,
inputSchema: S({ id: { type: "string", description: "Managed app id from apps_list, e.g. hermes." } }, ["id"]),
run: (a) => {
const id = str(a, "id");
if (!isManagedAppId(id)) throw new Error(`unknown managed application "${id}" — call apps_list for valid ids`);
return getManagedAppLogs(id);
},
},
{
name: "skills_search",
description:
"Semantic search across trusted SKILL.md files, the live MCP tool catalog and learned successful workflows. " +
"For MCP orientation, query mso-agent-bootstrap. Use this alone for capability research or unfamiliar single-step work. For a multi-step task call workflow_start directly — it already performs this search and avoids a duplicate startup call. " +
"The embedding runs locally with no API cost; untrusted skill instructions are excluded unless explicitly requested.",
chatgptDescription: "Find mso-agent-bootstrap",
scope: "read",
annotations: READ_ONLY,
inputSchema: S({
query: { type: "string", description: "The user's task or capability question in one complete sentence." },
top_k: { type: "number", minimum: 1, maximum: 20, description: "Maximum matches. Default 8." },
include_untrusted: { type: "boolean", description: "Include metadata-only matches from untrusted skill roots. Default false." },
}, ["query"]),
run: async (a, context) => {
const { TOOLS } = await import("./tools");
return searchSkillMemory(str(a, "query"), {
...(context.actor ? { recipeAccess: { actor: context.actor, scope: context.scope } } : {}),
topK: typeof a.top_k === "number" ? a.top_k : undefined,
includeUntrusted: a.include_untrusted === true,
toolDocs: TOOLS.map((t) => ({ name: t.name, description: t.description, scope: t.scope, inputSchema: t.inputSchema })),
});
},
},
{
name: "screen_capture",
description:
"Capture the authenticated MSO desktop and return it as an image. This is intentionally limited to " +
"MSO itself (no arbitrary URL capture), so it can be used to show visual progress without turning a read token " +
"into a browser exfiltration primitive. It saves a session-scoped artifact when a durable session exists, plus a 15-minute authenticated preview/download link. " +
"Choose macos, windows or dashboard; default macos.",
scope: "read",
annotations: READ_ONLY,
limit: { key: "screen.capture", max: 10, windowMs: 60_000 },
inputSchema: S({
shell: { type: "string", enum: ["macos", "windows", "dashboard"], description: "Desktop shell to render. Default macos." },
width: { type: "number", minimum: 900, maximum: 1920, description: "Viewport width. Default 1440." },
height: { type: "number", minimum: 600, maximum: 1200, description: "Viewport height. Default 900." },
}),
run: async (a, context) => {
const shell = typeof a.shell === "string" && ["macos", "windows", "dashboard"].includes(a.shell)
? (a.shell as "macos" | "windows" | "dashboard")
: "macos";
const shot = await captureMsoScreen({
shell,
width: typeof a.width === "number" ? a.width : undefined,
height: typeof a.height === "number" ? a.height : undefined,
});
const owner = context.principal && context.sessionId ? await ownedArtifactSession(context.principal,context.sessionId) : null;
const artifact = owner ? await saveSessionArtifact(owner,Buffer.from(shot.data,"base64"),{project:"mso",feature:`shell-${shell}`,environment:"local",width:shot.width,height:shot.height,producer:"mso",workflowId:context.workflowId}) : null;
const artifactPath = owner && artifact ? path.join(artifactPaths(owner).directory,artifact.relativePath) : undefined;
const stamp = new Date().toISOString().replace(/[:.]/g, "-");
const share = await createTempShare({
data: Buffer.from(shot.data, "base64"),
filename: `mso-${shot.shell}-${stamp}.png`,
mimeType: shot.mimeType,
ttlMs: 15 * 60_000,
maxDownloads: 5,
});
const previewUrl = tempShareUrl(share.id), downloadUrl = tempShareUrl(share.id, true);
const text = `MSO ${shot.shell} screenshot — ${shot.width}×${shot.height}\n` +
(artifactPath ? `Session artifact: ${artifactPath}\n` : "") +
`Temporary preview: ${previewUrl}\nDirect download: ${downloadUrl}\nExpires ${new Date(share.expiresAt).toISOString()} · ${share.downloadsLeft} authenticated downloads`;
return mcpDirect([
{ type: "image", data: shot.data, mimeType: shot.mimeType },
{ type: "text", text },
], false, {
result: { artifact, artifactPath, shell: shot.shell, width: shot.width, height: shot.height, mimeType: shot.mimeType, previewUrl, downloadUrl, expiresAt: share.expiresAt, downloadsLeft: share.downloadsLeft },
});
},
},
{
name: "browser_status",
description:
"State of the persistent Camoufox/noVNC browser session used by the human-facing MSO Browser app. Off is a healthy idle state. " +
"Automated website inspection should prefer the verified camoufox-browse skill with a disposable profile and should not start this persistent session just to inspect a public site. " +
"Returns installed/running/autostart only. The viewer URL and its one-time VNC password are DELIBERATELY not " +
"returned here — that session holds live Google and LinkedIn logins, so its credentials never leave " +
"the box through a tool result. Open Settings in mso to get them.",
scope: "read",
annotations: READ_ONLY,
inputSchema: S({}),
run: async () => {
const s = await camoufoxStatus();
return { installed: s.installed, running: s.running, autostart: s.enabled };
},
},
];