Add remote controller node wizard

This commit is contained in:
mmckeen
2026-04-28 15:13:11 +00:00
parent 9362668448
commit 401b646561
4 changed files with 393 additions and 1 deletions
+12
View File
@@ -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.
+170
View File
@@ -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 })
}
}
+184 -1
View File
@@ -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<string[]>([])
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<ControllerPlan | null>(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 (
<div className="space-y-6">
<section className="panel p-8">
<p className="text-[10px] font-mono uppercase tracking-wider text-[var(--nvidia-green)]">Guided Tasks</p>
<h1 className="mt-2 text-xl font-semibold uppercase tracking-wider text-[var(--foreground)]">Wizards</h1>
<p className="mt-2 max-w-3xl text-sm text-[var(--foreground-dim)]">
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.
</p>
</section>
<section className="panel overflow-hidden">
<div className="border-b border-[var(--border-subtle)] p-5">
<div className="flex items-center justify-between gap-4 max-md:flex-col max-md:items-start">
<div>
<h2 className="text-sm font-semibold uppercase tracking-wider text-[var(--foreground)]">Spawn a Controller Node</h2>
<p className="mt-1 text-xs text-[var(--foreground-dim)]">Prepare a remote VPS to run OpenShell Control near another OpenShell gateway or sandbox host.</p>
</div>
<span className="status-chip border border-[var(--border-subtle)] bg-[var(--background-tertiary)] px-2.5 py-1 text-[var(--foreground-dim)]">
remote control plane
</span>
</div>
</div>
<div className="grid grid-cols-1 gap-5 p-5 xl:grid-cols-[minmax(0,1fr)_minmax(360px,0.8fr)]">
<div className="space-y-5">
<div className="grid grid-cols-1 gap-4 md:grid-cols-2">
<label className="block space-y-2">
<span className="text-[10px] uppercase tracking-wider text-[var(--foreground-dim)]">Controller Name</span>
<input value={controllerName} onChange={(event) => setControllerName(event.target.value)} className="w-full rounded-sm border border-[var(--border-subtle)] bg-[var(--background-tertiary)] px-3 py-2 text-xs font-mono text-[var(--foreground)]" />
</label>
<label className="block space-y-2">
<span className="text-[10px] uppercase tracking-wider text-[var(--foreground-dim)]">Controller Host</span>
<input value={controllerHost} onChange={(event) => setControllerHost(event.target.value)} placeholder="vps.example.com" className="w-full rounded-sm border border-[var(--border-subtle)] bg-[var(--background-tertiary)] px-3 py-2 text-xs font-mono text-[var(--foreground)]" />
</label>
<label className="block space-y-2">
<span className="text-[10px] uppercase tracking-wider text-[var(--foreground-dim)]">SSH Target</span>
<input value={sshTarget} onChange={(event) => setSshTarget(event.target.value)} placeholder="ubuntu@vps.example.com" className="w-full rounded-sm border border-[var(--border-subtle)] bg-[var(--background-tertiary)] px-3 py-2 text-xs font-mono text-[var(--foreground)]" />
</label>
<label className="block space-y-2">
<span className="text-[10px] uppercase tracking-wider text-[var(--foreground-dim)]">Install Directory</span>
<input value={installDir} onChange={(event) => setInstallDir(event.target.value)} className="w-full rounded-sm border border-[var(--border-subtle)] bg-[var(--background-tertiary)] px-3 py-2 text-xs font-mono text-[var(--foreground)]" />
</label>
<label className="block space-y-2 md:col-span-2">
<span className="text-[10px] uppercase tracking-wider text-[var(--foreground-dim)]">Repository URL</span>
<input value={repoUrl} onChange={(event) => setRepoUrl(event.target.value)} className="w-full rounded-sm border border-[var(--border-subtle)] bg-[var(--background-tertiary)] px-3 py-2 text-xs font-mono text-[var(--foreground)]" />
</label>
<label className="block space-y-2">
<span className="text-[10px] uppercase tracking-wider text-[var(--foreground-dim)]">Dashboard Port</span>
<input value={dashboardPort} onChange={(event) => setDashboardPort(event.target.value)} className="w-full rounded-sm border border-[var(--border-subtle)] bg-[var(--background-tertiary)] px-3 py-2 text-xs font-mono text-[var(--foreground)]" />
</label>
<label className="block space-y-2">
<span className="text-[10px] uppercase tracking-wider text-[var(--foreground-dim)]">Terminal Port</span>
<input value={terminalPort} onChange={(event) => setTerminalPort(event.target.value)} className="w-full rounded-sm border border-[var(--border-subtle)] bg-[var(--background-tertiary)] px-3 py-2 text-xs font-mono text-[var(--foreground)]" />
</label>
<label className="block space-y-2">
<span className="text-[10px] uppercase tracking-wider text-[var(--foreground-dim)]">OpenClaw Dashboard URL</span>
<input value={openClawDashboardUrl} onChange={(event) => setOpenClawDashboardUrl(event.target.value)} className="w-full rounded-sm border border-[var(--border-subtle)] bg-[var(--background-tertiary)] px-3 py-2 text-xs font-mono text-[var(--foreground)]" />
</label>
<label className="block space-y-2">
<span className="text-[10px] uppercase tracking-wider text-[var(--foreground-dim)]">OpenShell Gateway</span>
<input value={openshellGateway} onChange={(event) => setOpenshellGateway(event.target.value)} className="w-full rounded-sm border border-[var(--border-subtle)] bg-[var(--background-tertiary)] px-3 py-2 text-xs font-mono text-[var(--foreground)]" />
</label>
</div>
<label className="flex items-start gap-3 rounded-sm border border-[var(--border-subtle)] bg-[var(--background-tertiary)] p-3">
<input type="checkbox" checked={exposePublicly} onChange={(event) => setExposePublicly(event.target.checked)} className="mt-0.5 h-4 w-4 accent-[var(--nvidia-green)]" />
<span>
<span className="block text-xs font-mono uppercase tracking-wider text-[var(--foreground)]">Controller UI is directly reachable</span>
<span className="mt-1 block text-[11px] text-[var(--foreground-dim)]">Leave this off when you access the VPS through SSH tunnels, WireGuard, or Tailscale.</span>
</span>
</label>
<button type="button" onClick={generateControllerPlan} disabled={controllerPlanning || !controllerHost.trim()} className="rounded-sm bg-[var(--nvidia-green)] px-4 py-2 text-xs font-mono uppercase tracking-wider text-black disabled:opacity-50">
{controllerPlanning ? "Preparing..." : "Generate Launch Kit"}
</button>
{controllerMessage && <div className="rounded-sm border border-[var(--border-subtle)] bg-[var(--background-tertiary)] p-3 text-sm text-[var(--foreground-dim)]">{controllerMessage}</div>}
</div>
<div className="space-y-4">
<div className="rounded-sm border border-[var(--border-subtle)] bg-[var(--background-tertiary)] p-4">
<h3 className="text-xs font-semibold uppercase tracking-wider text-[var(--foreground)]">Topology</h3>
<div className="mt-3 space-y-2 text-xs text-[var(--foreground-dim)]">
<p>Controller VPS: {controllerHost || "not set"}</p>
<p>Sandbox host/gateway: {openshellGateway || "nemoclaw"}</p>
<p>OpenClaw upstream: {openClawDashboardUrl}</p>
</div>
</div>
{controllerPlan ? (
<div className="space-y-4">
<div className="rounded-sm border border-[var(--border-subtle)] bg-[var(--background-tertiary)] p-4">
<div className="flex items-center justify-between gap-3">
<h3 className="text-xs font-semibold uppercase tracking-wider text-[var(--foreground)]">SSH Bootstrap</h3>
<button type="button" onClick={() => copyText(controllerPlan.commands.ssh, "SSH bootstrap")} className="action-button px-3 py-1.5 text-[10px]">Copy</button>
</div>
<pre className="mt-3 max-h-72 overflow-auto whitespace-pre-wrap rounded-sm border border-[var(--border-subtle)] bg-[var(--background)] p-3 text-[11px] leading-5 text-[var(--foreground-dim)]">{controllerPlan.commands.ssh}</pre>
</div>
<div className="rounded-sm border border-[var(--border-subtle)] bg-[var(--background-tertiary)] p-4">
<div className="flex items-center justify-between gap-3">
<h3 className="text-xs font-semibold uppercase tracking-wider text-[var(--foreground)]">Controller Env</h3>
<button type="button" onClick={() => copyText(controllerPlan.env, "Controller env")} className="action-button px-3 py-1.5 text-[10px]">Copy</button>
</div>
<pre className="mt-3 max-h-56 overflow-auto whitespace-pre-wrap rounded-sm border border-[var(--border-subtle)] bg-[var(--background)] p-3 text-[11px] leading-5 text-[var(--foreground-dim)]">{controllerPlan.env}</pre>
</div>
<div className="rounded-sm border border-[var(--border-subtle)] bg-[var(--background-tertiary)] p-4">
<h3 className="text-xs font-semibold uppercase tracking-wider text-[var(--foreground)]">Readiness Checks</h3>
<div className="mt-3 space-y-2">
{controllerPlan.checks.map((check) => (
<p key={check} className="text-xs text-[var(--foreground-dim)]">{check}</p>
))}
</div>
</div>
</div>
) : (
<div className="rounded-sm border border-[var(--border-subtle)] bg-[var(--background-tertiary)] p-4 text-sm text-[var(--foreground-dim)]">
Enter the remote node details to generate a controller bootstrap command and matching environment block.
</div>
)}
</div>
</div>
</section>
<section className="panel overflow-hidden">
<div className="border-b border-[var(--border-subtle)] p-5">
<div className="flex items-center justify-between gap-4 max-md:flex-col max-md:items-start">
+27
View File
@@ -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')