From 401b6465615c4081cd59b4eb36d7bed9c88f2329 Mon Sep 17 00:00:00 2001 From: mmckeen Date: Tue, 28 Apr 2026 15:11:53 +0000 Subject: [PATCH] Add remote controller node wizard --- README.md | 12 ++ app/api/controller-node/plan/route.ts | 170 +++++++++++++++++++++++ app/components/WizardPanel.tsx | 185 ++++++++++++++++++++++++- tests/controller-node-wizard-check.mjs | 27 ++++ 4 files changed, 393 insertions(+), 1 deletion(-) create mode 100644 app/api/controller-node/plan/route.ts create mode 100644 tests/controller-node-wizard-check.mjs diff --git a/README.md b/README.md index 87fe8d6..73c6315 100644 --- a/README.md +++ b/README.md @@ -193,6 +193,18 @@ The custom server in `server.mjs` also handles websocket upgrades for: Those upgrade paths are protected by the same auth cookie as the HTTP routes. +## Remote Controller Nodes + +The Wizards page includes **Spawn a Controller Node** for preparing a small OpenShell Control install on another VPS. This is intended for topologies where the browser-facing dashboard and the OpenShell gateway/sandbox hosts are not the same machine. + +The wizard generates: + +- an SSH bootstrap command for the remote VPS; +- a controller `.env` block with `OPENSHELL_GATEWAY`, `OPENCLAW_DASHBOARD_URL`, terminal sidecar settings, and `OPENCLAW_INSTANCE_REGISTRY_JSON`; +- readiness checks for OpenShell CLI reachability, OpenClaw dashboard access, and port exposure. + +This first step does not run arbitrary SSH from the web UI. It gives the operator a repeatable launch kit so the remote controller can be installed over SSH, WireGuard, Tailscale, or a private management network. After the controller is running, use its local OpenShell CLI context to manage the sandboxes reachable from that VPS. + ## Inference Endpoints Inference endpoint configuration is development-stage. diff --git a/app/api/controller-node/plan/route.ts b/app/api/controller-node/plan/route.ts new file mode 100644 index 0000000..c899957 --- /dev/null +++ b/app/api/controller-node/plan/route.ts @@ -0,0 +1,170 @@ +import { NextResponse } from "next/server" + +type ControllerPlanRequest = { + controllerName?: unknown + controllerHost?: unknown + sshTarget?: unknown + installDir?: unknown + repoUrl?: unknown + dashboardPort?: unknown + terminalPort?: unknown + openClawDashboardUrl?: unknown + openshellGateway?: unknown + exposePublicly?: unknown +} + +const DEFAULT_REPO_URL = process.env.OPENSHELL_CONTROL_REPO_URL || "https://github.com/NVIDIA/nemoclaw-dashboard.git" +const SAFE_NAME = /^[a-z0-9]([a-z0-9-]*[a-z0-9])?$/ +const SAFE_SSH_TARGET = /^[a-zA-Z0-9._-]+@[a-zA-Z0-9._-]+(?::[0-9]{1,5})?$/ + +function text(value: unknown, fallback = "") { + return typeof value === "string" ? value.trim() : fallback +} + +function numberValue(value: unknown, fallback: number) { + const parsed = typeof value === "number" ? value : Number.parseInt(String(value ?? ""), 10) + return Number.isFinite(parsed) && parsed > 0 && parsed <= 65535 ? parsed : fallback +} + +function shellSingleQuote(value: string) { + return `'${value.replaceAll("'", "'\\''")}'` +} + +function validateUrl(value: string, label: string) { + try { + const parsed = new URL(value) + if (!["http:", "https:"].includes(parsed.protocol)) throw new Error() + return parsed.toString() + } catch { + throw new Error(`${label} must be an http(s) URL`) + } +} + +function validateInstallDir(value: string) { + if (!value || value.includes("\n") || value.includes("\0") || value.startsWith("-") || value.includes("..")) { + throw new Error("installDir must be a safe absolute path or home-relative directory") + } + if (!value.startsWith("/") && !/^[a-zA-Z0-9._/-]+$/.test(value)) { + throw new Error("installDir can only contain letters, numbers, dots, underscores, hyphens, and slashes") + } + return value.replace(/\/+$/, "") || "openshell-control" +} + +function buildEnvBlock(params: { + controllerName: string + controllerHost: string + dashboardPort: number + terminalPort: number + openClawDashboardUrl: string + openshellGateway: string + exposePublicly: boolean +}) { + const dashboardOrigin = `http://${params.controllerHost}:${params.dashboardPort}` + const registry = [ + { + id: params.controllerName, + label: `${params.controllerName} controller`, + dashboardUrl: params.openClawDashboardUrl, + controlUiOrigin: dashboardOrigin, + terminalServerUrl: `http://127.0.0.1:${params.terminalPort}`, + loopbackOnly: !params.exposePublicly, + default: true, + }, + ] + + return [ + `NEXT_PUBLIC_DASHBOARD_PORT=${params.dashboardPort}`, + "NEXT_PUBLIC_API_BASE=/api", + "NEXT_PUBLIC_ENABLE_SANDBOX_OPERATIONS=true", + `OPENSHELL_GATEWAY=${params.openshellGateway}`, + "OPEN_SHELL_CONTAINER=openshell-cluster-nemoclaw", + "TERMINAL_SERVER_AUTOSTART=true", + `TERMINAL_SERVER_PORT=${params.terminalPort}`, + `OPENCLAW_DASHBOARD_URL=${params.openClawDashboardUrl}`, + `OPENCLAW_INSTANCE_REGISTRY_JSON=${JSON.stringify(registry)}`, + ].join("\n") +} + +export async function POST(request: Request) { + try { + const body = (await request.json().catch(() => ({}))) as ControllerPlanRequest + const controllerName = text(body.controllerName, "remote-controller").toLowerCase() + if (!SAFE_NAME.test(controllerName) || controllerName.length > 63) { + throw new Error("controllerName must be lowercase letters, numbers, and internal hyphens") + } + + const controllerHost = text(body.controllerHost) + if (!controllerHost) throw new Error("controllerHost is required") + + const sshTarget = text(body.sshTarget) + if (sshTarget && !SAFE_SSH_TARGET.test(sshTarget)) { + throw new Error("sshTarget must look like user@host or user@host:port") + } + + const installDir = validateInstallDir(text(body.installDir, "openshell-control")) + const repoUrl = validateUrl(text(body.repoUrl, DEFAULT_REPO_URL), "repoUrl") + const dashboardPort = numberValue(body.dashboardPort, 3000) + const terminalPort = numberValue(body.terminalPort, 3011) + const openClawDashboardUrl = validateUrl(text(body.openClawDashboardUrl, "http://127.0.0.1:18789/"), "openClawDashboardUrl") + const openshellGateway = text(body.openshellGateway, "nemoclaw") + const exposePublicly = Boolean(body.exposePublicly) + const envBlock = buildEnvBlock({ + controllerName, + controllerHost, + dashboardPort, + terminalPort, + openClawDashboardUrl, + openshellGateway, + exposePublicly, + }) + + const remoteBootstrap = [ + "set -euo pipefail", + `INSTALL_DIR=${shellSingleQuote(installDir)}`, + `REPO_URL=${shellSingleQuote(repoUrl)}`, + 'if ! command -v git >/dev/null 2>&1; then echo "git is required" >&2; exit 1; fi', + 'if ! command -v node >/dev/null 2>&1; then echo "Node.js 20+ is required" >&2; exit 1; fi', + 'if [ -d "$INSTALL_DIR/.git" ]; then git -C "$INSTALL_DIR" pull --ff-only; else mkdir -p "$(dirname "$INSTALL_DIR")"; git clone --depth=1 "$REPO_URL" "$INSTALL_DIR"; fi', + 'cd "$INSTALL_DIR"', + "./install.sh --no-build --no-audit", + "cat > .env.controller-node <<'ENV'", + envBlock, + "ENV", + "cat .env.controller-node >> .env.local", + "npm run build", + `echo "Controller node ready on http://${controllerHost}:${dashboardPort}"`, + ].join("\n") + + const sshCommand = sshTarget + ? `ssh ${sshTarget.includes(":") ? `-p ${sshTarget.split(":").pop()} ${sshTarget.split(":")[0]}` : sshTarget} 'bash -s' <<'REMOTE_CONTROLLER'\n${remoteBootstrap}\nREMOTE_CONTROLLER` + : remoteBootstrap + + return NextResponse.json({ + ok: true, + controller: { + name: controllerName, + url: `http://${controllerHost}:${dashboardPort}`, + host: controllerHost, + dashboardPort, + terminalPort, + installDir, + }, + env: envBlock, + commands: { + ssh: sshCommand, + localBootstrap: remoteBootstrap, + start: `cd ${shellSingleQuote(installDir)} && npm run start`, + terminal: `cd ${shellSingleQuote(installDir)} && npm run terminal-server`, + }, + checks: [ + "OpenShell CLI is installed on the controller node and can reach the gateway.", + `The controller can reach ${openClawDashboardUrl}.`, + `Port ${dashboardPort} is reachable from your browser or through an SSH tunnel.`, + `Port ${terminalPort} stays private unless you intentionally expose terminal transport.`, + ], + }) + } catch (error) { + const message = error instanceof Error ? error.message : "Failed to build controller node plan" + return NextResponse.json({ ok: false, error: message }, { status: 400 }) + } +} diff --git a/app/components/WizardPanel.tsx b/app/components/WizardPanel.tsx index 1b358a2..2fcb9ae 100644 --- a/app/components/WizardPanel.tsx +++ b/app/components/WizardPanel.tsx @@ -12,6 +12,25 @@ type BlueprintOption = { type WizardStep = "source" | "target" | "options" | "review" | "run" +type ControllerPlan = { + controller: { + name: string + url: string + host: string + dashboardPort: number + terminalPort: number + installDir: string + } + env: string + commands: { + ssh: string + localBootstrap: string + start: string + terminal: string + } + checks: string[] +} + const steps: Array<{ key: WizardStep; label: string }> = [ { key: "source", label: "Source" }, { key: "target", label: "Target" }, @@ -51,6 +70,19 @@ export default function WizardPanel({ const [running, setRunning] = useState(false) const [message, setMessage] = useState("") const [runLog, setRunLog] = useState([]) + const [controllerName, setControllerName] = useState("remote-controller") + const [controllerHost, setControllerHost] = useState("") + const [sshTarget, setSshTarget] = useState("") + const [installDir, setInstallDir] = useState("openshell-control") + const [repoUrl, setRepoUrl] = useState("https://github.com/NVIDIA/nemoclaw-dashboard.git") + const [dashboardPort, setDashboardPort] = useState("3000") + const [terminalPort, setTerminalPort] = useState("3011") + const [openClawDashboardUrl, setOpenClawDashboardUrl] = useState("http://127.0.0.1:18789/") + const [openshellGateway, setOpenshellGateway] = useState("nemoclaw") + const [exposePublicly, setExposePublicly] = useState(false) + const [controllerPlan, setControllerPlan] = useState(null) + const [controllerMessage, setControllerMessage] = useState("") + const [controllerPlanning, setControllerPlanning] = useState(false) const sourceSandbox = useMemo( () => sandboxes.find((sandbox) => sandbox.id === sourceSandboxId) || null, @@ -164,16 +196,167 @@ export default function WizardPanel({ } } + async function generateControllerPlan() { + try { + setControllerPlanning(true) + setControllerMessage("") + setControllerPlan(null) + + const response = await fetch("/api/controller-node/plan", { + method: "POST", + headers: { "Content-Type": "application/json" }, + body: JSON.stringify({ + controllerName, + controllerHost, + sshTarget, + installDir, + repoUrl, + dashboardPort, + terminalPort, + openClawDashboardUrl, + openshellGateway, + exposePublicly, + }), + }) + const data = await response.json() + if (!response.ok) throw new Error(data.error || "Failed to generate controller node plan") + setControllerPlan(data) + setControllerMessage(`Launch kit ready for ${data.controller.url}.`) + } catch (error) { + setControllerMessage(error instanceof Error ? error.message : "Failed to generate controller node plan") + } finally { + setControllerPlanning(false) + } + } + + async function copyText(value: string, label: string) { + try { + await navigator.clipboard.writeText(value) + setControllerMessage(`${label} copied.`) + } catch { + setControllerMessage("Clipboard access was blocked. Select the command text manually.") + } + } + return (

Guided Tasks

Wizards

- Step-by-step workflows for common operations. The first wizard clones one sandbox into another using backup and restore. + Step-by-step workflows for common operations, including remote controller bootstrap and sandbox cloning.

+
+
+
+
+

Spawn a Controller Node

+

Prepare a remote VPS to run OpenShell Control near another OpenShell gateway or sandbox host.

+
+ + remote control plane + +
+
+ +
+
+
+ + + + + + + + + +
+ + + {controllerMessage &&
{controllerMessage}
} +
+ +
+
+

Topology

+
+

Controller VPS: {controllerHost || "not set"}

+

Sandbox host/gateway: {openshellGateway || "nemoclaw"}

+

OpenClaw upstream: {openClawDashboardUrl}

+
+
+ {controllerPlan ? ( +
+
+
+

SSH Bootstrap

+ +
+
{controllerPlan.commands.ssh}
+
+
+
+

Controller Env

+ +
+
{controllerPlan.env}
+
+
+

Readiness Checks

+
+ {controllerPlan.checks.map((check) => ( +

{check}

+ ))} +
+
+
+ ) : ( +
+ Enter the remote node details to generate a controller bootstrap command and matching environment block. +
+ )} +
+
+
+
diff --git a/tests/controller-node-wizard-check.mjs b/tests/controller-node-wizard-check.mjs new file mode 100644 index 0000000..4aaa758 --- /dev/null +++ b/tests/controller-node-wizard-check.mjs @@ -0,0 +1,27 @@ +import assert from 'node:assert/strict' +import { readFile } from 'node:fs/promises' +import path from 'node:path' + +const root = process.cwd() + +const [wizardSource, routeSource] = await Promise.all([ + readFile(path.join(root, 'app/components/WizardPanel.tsx'), 'utf8'), + readFile(path.join(root, 'app/api/controller-node/plan/route.ts'), 'utf8'), +]) + +assert.match(wizardSource, /Spawn a Controller Node/, 'wizard must expose a controller-node workflow') +assert.match(wizardSource, /Generate Launch Kit/, 'controller workflow must generate a launch kit') +assert.match(wizardSource, /\/api\/controller-node\/plan/, 'wizard must call the controller-node plan API') +assert.match(wizardSource, /OPENCLAW_DASHBOARD_URL|OpenClaw Dashboard URL/, 'wizard must collect the remote OpenClaw upstream') +assert.match(wizardSource, /OPENSHELL_GATEWAY|OpenShell Gateway/, 'wizard must collect the remote OpenShell gateway context') +assert.match(wizardSource, /Controller Env/, 'wizard must expose the generated controller environment') +assert.match(wizardSource, /Readiness Checks/, 'wizard must show remote readiness checks') + +assert.match(routeSource, /OPENCLAW_INSTANCE_REGISTRY_JSON/, 'plan API must configure the OpenClaw instance registry') +assert.match(routeSource, /TERMINAL_SERVER_AUTOSTART=true/, 'plan API must enable the terminal sidecar for controller nodes') +assert.match(routeSource, /sshTarget/, 'plan API must support SSH bootstrap output') +assert.match(routeSource, /npm run build/, 'plan API must produce a complete install/build command') +assert.match(routeSource, /OpenShell CLI is installed/, 'plan API must return operational readiness checks') +assert.doesNotMatch(routeSource, /\/home\/nvidia|\/Users\/markmckeen/, 'plan API must not bake in developer machine paths') + +console.log('controller-node-wizard-check: PASS controller node wizard assertions')