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 { sessionArtifactEnvironment } from "@/lib/agent/artifact-session";
import { cancelExecJob, getExecJob, runCommand, startExecJob } from "@/lib/host/exec-api";
import { assertDelegatedWritePath, copy, makeDir, move, remove, writeFileGuarded } from "@/lib/host/fs-api";
import { resolveProjectHint, runProjectFunction } from "@/lib/host/projects-api";
import { importOpenAiProvidedFile } from "./openai-file-upload";
import { type McpTool, opt, PATH_P, S, str } from "./tool-kit";
import { requireWorkflowExecCwd, requireWorkflowMutationPath, requireWorkflowProjectTarget } from "./workflow-workspace-guard";
async function requireDelegatedPath(context: Parameters<McpTool["run"]>[1], target: string) { if (context.scope !== "exec") await assertDelegatedWritePath(target); }
export const MUTATE_TOOLS: McpTool[] = [
{
name: "fs_write",
limit: { key: "fs.write", max: 120, windowMs: 60_000 },
audit: { action: "fs.write" as const, targetArg: "path" },
description: "Create or overwrite a text file on the VPS. Inspect with fs_read first and pass its SHA-256 as expected_sha256 to refuse a stale overwrite when another process changed the file. Omitting the hash keeps legacy overwrite behaviour. Bounded to OS_FS_WRITE_ROOTS (home + ~/projects by default).",
scope: "write",
annotations: { idempotentHint: true },
actionContract: { phase: "mutate", target: "filesystem-text", sourceOfTruth: "live", discover: ["fs_read"], validators: ["path-policy", "sha256-cas"], verify: ["fs_read"], confirmation: "contextual", concurrency: "hash", presentation: "structured" },
inputSchema: S({ ...PATH_P, content: { type: "string" }, expected_sha256: { type: "string", description: "Optional SHA-256 returned by fs_read; refuse if the current file no longer matches." } }, ["path", "content"]),
run: async (a, context) => {
const target = str(a, "path");
await requireWorkflowMutationPath(context, target);
await requireDelegatedPath(context, target);
return { ok: true, ...(await writeFileGuarded({ path: target, content: typeof a.content === "string" ? a.content : "", expectedSha256: opt(a, "expected_sha256") })) };
},
},
{
name: "fs_upload_file",
limit: { key: "fs.upload", max: 20, windowMs: 60_000 },
audit: { action: "fs.upload" as const, targetArg: "dest" },
description: "Import one ChatGPT conversation/generated PNG, WebP, JPEG, JSON or ZIP file through openai/fileParams. MSO validates temporary URL host, type, size and content before writing inside OS_FS_WRITE_ROOTS. All Azure file hosts require exact Owner allowlisting; DCR metadata never grants host trust. Same bytes are idempotent; different existing bytes fail by default. conflict=rename is deterministic; conflict=replace requires expected_sha256.",
scope: "write",
annotations: { destructiveHint: true, openWorldHint: true, idempotentHint: true },
actionContract: { phase: "mutate", target: "artifact-ingress", sourceOfTruth: "provider", validators: ["openai-file-provenance", "content-type", "content-size", "content-structure", "destination-policy"], verify: ["fs_read"], confirmation: "contextual", concurrency: "hash", presentation: "structured" },
meta: { "openai/fileParams": ["file"] },
inputSchema: S({
file: { type: "object", description: "ChatGPT-provided file reference. Select or attach exactly one PNG, WebP, JPEG, JSON or ZIP file.", properties: { download_url: { type: "string" }, file_id: { type: "string" }, mime_type: { type: "string" }, file_name: { type: "string" }, name: { type: "string" }, size: { type: "number" } }, required: ["download_url", "file_id"], additionalProperties: true },
dest: { type: "string", description: "Existing destination directory on the VPS, within OS_FS_WRITE_ROOTS." },
filename: { type: "string", description: "Optional safe destination basename; extension must match the validated file type." },
conflict: { type: "string", enum: ["error", "rename", "replace"], description: "Default error. rename chooses a deterministic content-hash suffix. replace requires expected_sha256." },
expected_sha256: { type: "string", description: "Required only for conflict=replace; SHA-256 from a prior read/export of the current destination." },
}, ["file", "dest"]),
run: async (a, context) => {
const dest = str(a, "dest");
await requireWorkflowMutationPath(context, dest);
await requireDelegatedPath(context, dest);
return importOpenAiProvidedFile({ file: a.file, dest, filename: opt(a, "filename"), conflict: opt(a, "conflict") as "error" | "rename" | "replace" | undefined, expectedSha256: opt(a, "expected_sha256") });
},
},
{
name: "fs_mkdir",
limit: { key: "fs.mkdir", max: 120, windowMs: 60_000 },
audit: { action: "fs.mkdir" as const, targetArg: "path" },
description: "Create a directory (and any missing parents) on the VPS.",
scope: "write",
annotations: { idempotentHint: true },
inputSchema: S(PATH_P, ["path"]),
run: async (a, context) => { const target = str(a, "path"); await requireWorkflowMutationPath(context, target); await requireDelegatedPath(context, target); await makeDir(target); return { ok: true, path: a.path }; },
},
{
name: "fs_move",
limit: { key: "fs.move", max: 120, windowMs: 60_000 },
audit: { action: "fs.move" as const, targetArg: "from" },
description: "Move or rename a file or directory. Refuses when the source holds credential paths.",
scope: "write",
inputSchema: S({ from: { type: "string" }, to: { type: "string" } }, ["from", "to"]),
run: async (a, context) => { const from = str(a, "from"), to = str(a, "to"); await requireWorkflowMutationPath(context, from); await requireWorkflowMutationPath(context, to); await requireDelegatedPath(context, from); await requireDelegatedPath(context, to); await move(from, to); return { ok: true }; },
},
{
name: "fs_copy",
limit: { key: "fs.copy", max: 60, windowMs: 60_000 },
audit: { action: "fs.copy" as const, targetArg: "from" },
description: "Copy a file or directory. The cockpit's own secrets are skipped rather than duplicated.",
scope: "write",
inputSchema: S({ from: { type: "string" }, to: { type: "string" } }, ["from", "to"]),
run: async (a, context) => { const from = str(a, "from"), to = str(a, "to"); await requireWorkflowMutationPath(context, to); await requireDelegatedPath(context, to); await copy(from, to); return { ok: true }; },
},
{
name: "fs_delete",
limit: { key: "fs.delete", max: 60, windowMs: 60_000 },
audit: { action: "fs.delete" as const, targetArg: "path" },
description: "Delete a file or directory on the VPS. PERMANENT — there is no trash and no undo. Confirm with the user before calling this on anything you did not create in this conversation.",
scope: "write",
annotations: { destructiveHint: true },
inputSchema: S(PATH_P, ["path"]),
run: async (a, context) => { const target = str(a, "path"); await requireWorkflowMutationPath(context, target); await requireDelegatedPath(context, target); await remove(target); return { ok: true, path: a.path }; },
},
{
name: "project_function_call",
limit: { key: "projects.function", max: 60, windowMs: 60_000 },
audit: {
action: "exec.run" as const,
targetArg: "project",
outcome: (r) => {
const { code } = r as { code: number };
return { ok: code === 0, action: "exec.run", detail: `project function exit ${code}` };
},
},
description: "Execute ONE function explicitly declared by a validated project's .mso/functions.json. This is project code execution and therefore requires exec scope. The manifest supplies fixed argv; model/user input is passed only as JSON on stdin and is NEVER interpolated into a shell command. Call project_capabilities first for function names and schemas. Projects without an opt-in manifest expose nothing. A function may return a validated bounded direct-image envelope for visual debugging; invalid envelopes remain ordinary text output.",
scope: "exec",
annotations: { destructiveHint: true, openWorldHint: true },
inputSchema: S({
project: { type: "string", description: "Exact project id from projects_list, absolute path, name or alias." },
name: { type: "string", description: "Function name returned by project_capabilities." },
input: { type: "object", description: "JSON object passed to the project function on stdin.", additionalProperties: true },
}, ["project", "name", "input"]),
run: async (a, context) => {
const project = await resolveProjectHint(str(a, "project"));
if (!project) throw new Error(`project not found: ${String(a.project)}`);
await requireWorkflowProjectTarget(context, project.path);
return (await import("./project-function-content")).projectFunctionContent(await runProjectFunction(project.path, str(a, "name"), a.input));
},
},
{
name: "exec_job_start",
limit: { key: "exec.job.start", max: 12, windowMs: 60_000 },
audit: {
action: "exec.job.start" as const,
targetArg: "command",
outcome: (r) => {
const row = r as { state: string };
const refused = row.state === "refused";
return { ok: !refused, action: refused ? "exec.blocked" : "exec.job.start", detail: refused ? "refused" : "started" };
},
},
description: "Start one bounded asynchronous shell job for legitimate test/build pipelines that exceed exec_run's 30s request budget. The job is client/workflow-bound, capped at 20 minutes and 1 MiB per output stream, limited to four concurrent jobs per client, and uses the same cwd jail and catastrophic-command filter as exec_run. Use exec_job_status to read it and exec_job_cancel to stop it.",
scope: "exec",
annotations: { destructiveHint: true, openWorldHint: true },
inputSchema: S({
command: { type: "string", description: "The shell command line to run asynchronously." },
cwd: { type: "string", description: "Working directory. Defaults to the owner's home." },
}, ["command"]),
run: async (a, context) => {
const cwd = opt(a, "cwd");
await requireWorkflowExecCwd(context, cwd);
return startExecJob({
artifactEnv: await sessionArtifactEnvironment(context),
command: str(a, "command"), cwd, actor: context.workflowActor ?? context.actor, workflowId: context.workflowId,
});
},
},
{
name: "exec_job_status",
limit: { key: "exec.job.status", max: 120, windowMs: 60_000 },
description:
"Read one asynchronous exec job owned by this MCP client. Returns state, bounded stdout/stderr, exit code when finished, and whether output was truncated.",
scope: "read",
annotations: { readOnlyHint: true, idempotentHint: true },
result: { maxTextBytes: 64 * 1024, overflowHint: "The job output is larger than the model context budget; rerun a focused grep/tail after completion if more detail is needed." },
inputSchema: S({ job_id: { type: "string", description: "Exact id returned by exec_job_start." } }, ["job_id"]),
run: (a, context) => Promise.resolve(getExecJob(str(a, "job_id"), context.workflowActor ?? context.actor, context.workflowId)),
},
{
name: "exec_job_cancel",
limit: { key: "exec.job.cancel", max: 30, windowMs: 60_000 },
audit: { action: "exec.job.cancel" as const, targetArg: "job_id" },
description:
"Cancel one still-running asynchronous exec job owned by this MCP client. Repeated cancellation is idempotent.",
scope: "exec",
annotations: { destructiveHint: true, idempotentHint: true },
inputSchema: S({ job_id: { type: "string", description: "Exact id returned by exec_job_start." } }, ["job_id"]),
run: (a, context) => Promise.resolve(cancelExecJob(str(a, "job_id"), context.workflowActor ?? context.actor, context.workflowId)),
},
{
name: "exec_run",
limit: { key: "exec", max: 60, windowMs: 60_000 },
audit: {
action: "exec.run" as const,
targetArg: "command",
// runCommand REFUSES by returning {code:126, stderr:"refused: …"}, it does not
// throw — so "the handler did not throw" is not success here. Mirrors
// app/api/v1/exec/run/route.ts:39-45 exactly; the two must not disagree about
// what the same command did.
outcome: (r) => {
const { code, stderr } = r as { code: number; stderr: string };
const blocked = code === 126 && stderr.startsWith("refused:");
return { ok: !blocked && code === 0, action: blocked ? "exec.blocked" : "exec.run", detail: `exit ${code}` };
},
},
description: "Run a shell command on the VPS as the owner and return stdout, stderr and exit code. Do not use this as the first call: start multi-step work with workflow_start and prefer bounded reads or read_pipeline. FULL HOST POWER — prefer fs_* and sys_* tools whenever they cover the task; they are bounded and this is not. Catastrophic patterns (rm -rf /, fork bombs, disk wipes) are refused by the server. Long-running or interactive commands will time out: this is not a terminal session.",
chatgptDescription: "Last resort shell; prefer reads/read_pipeline first.", scope: "exec",
annotations: { destructiveHint: true, openWorldHint: true },
result: { maxTextBytes: 48 * 1024, overflowHint: "Command output was compacted; rerun a narrower command (grep/head/tail) for the omitted evidence." },
inputSchema: S({
command: { type: "string", description: "The shell command line to run." },
cwd: { type: "string", description: "Working directory. Defaults to the owner's home." },
}, ["command"]),
run: async (a, context) => {
const cwd = opt(a, "cwd");
await requireWorkflowExecCwd(context, cwd);
return runCommand(str(a, "command"), cwd, await sessionArtifactEnvironment(context));
},
},
];