+ {cloneWizardOpen && <>
{steps.map((step, index) => (
+ >}
)
diff --git a/app/lib/controllerNodePlan.ts b/app/lib/controllerNodePlan.ts
new file mode 100644
index 0000000..9c0e071
--- /dev/null
+++ b/app/lib/controllerNodePlan.ts
@@ -0,0 +1,268 @@
+import { randomBytes } from "node:crypto"
+
+export type ControllerPlanRequest = {
+ controllerName?: unknown
+ controllerHost?: unknown
+ sshTarget?: unknown
+ installDir?: unknown
+ repoUrl?: unknown
+ dashboardPort?: unknown
+ terminalPort?: unknown
+ openclawUrl?: unknown
+ openClawDashboardUrl?: unknown
+ openshellGateway?: unknown
+ parentControllerUrl?: unknown
+ existingToken?: unknown
+}
+
+export type ControllerNodePlan = {
+ controller: {
+ name: string
+ host: string
+ url: string
+ sshTarget: string
+ installDir: string
+ repoUrl: string
+ parentControllerUrl: string
+ dashboardPort: number
+ terminalPort: number
+ }
+ env: string
+ serviceUnit: string
+ commands: {
+ ssh: string
+ localBootstrap: string
+ start: string
+ terminal: string
+ }
+ checks: string[]
+}
+
+const DEFAULT_REPO_URL = process.env.OPENSHELL_CONTROL_REPO_URL || "https://github.com/mmckeen-nv/openshell_controller.git"
+const SAFE_NAME = /^[a-z0-9][a-z0-9-]{1,62}$/i
+const SAFE_HOST = /^[a-z0-9.-]+$/i
+const SAFE_SSH_TARGET = /^([a-z0-9._-]+@)?[a-z0-9.-]+(:[0-9]{1,5})?$/i
+
+function text(value: unknown, fallback = "") {
+ return typeof value === "string" ? value.trim() : fallback
+}
+
+function numberValue(value: unknown, fallback: number) {
+ const parsed = Number.parseInt(String(value ?? ""), 10)
+ return Number.isFinite(parsed) && parsed > 0 && parsed <= 65535 ? parsed : fallback
+}
+
+export function shellSingleQuote(value: string) {
+ return `'${value.replace(/'/g, "'\\''")}'`
+}
+
+function sshBootstrapInvocation(target: string) {
+ const match = target.match(/^((?:[a-z0-9._-]+@)?[a-z0-9.-]+)(?::([0-9]{1,5}))?$/i)
+ if (!match) throw new Error("sshTarget must look like user@host or user@host:port")
+ const [, host, targetPort] = match
+ return targetPort ? `ssh -p ${targetPort} ${shellSingleQuote(host)}` : `ssh ${shellSingleQuote(host)}`
+}
+
+function validateUrl(value: string, label: string) {
+ if (/^git@[a-z0-9.-]+:[a-z0-9._/-]+\.git$/i.test(value)) return value
+ if (/^ssh:\/\/[^\s]+$/i.test(value)) return value
+ try {
+ const parsed = new URL(value)
+ if (parsed.protocol === "https:" || parsed.protocol === "http:") return value
+ } catch {
+ // handled below
+ }
+ throw new Error(`${label} must be an http(s), ssh, or git SSH URL`)
+}
+
+function validateHttpUrl(value: string, label: string) {
+ try {
+ const parsed = new URL(value)
+ if (parsed.protocol === "https:" || parsed.protocol === "http:") return value.replace(/\/$/, "")
+ } catch {
+ // handled below
+ }
+ throw new Error(`${label} must be an http(s) URL`)
+}
+
+function validateInstallDir(value: string) {
+ if (!value || value.includes("\0") || value.includes("\n")) throw new Error("installDir is invalid")
+ if (!value.startsWith("/")) throw new Error("installDir must be an absolute path")
+ return value.replace(/\/$/, "")
+}
+
+function controllerToken(value: unknown) {
+ const existing = text(value)
+ if (existing) {
+ if (!/^[a-zA-Z0-9._~:-]{20,256}$/.test(existing)) throw new Error("existingToken contains unsupported characters")
+ return existing
+ }
+ return randomBytes(32).toString("base64url")
+}
+
+function buildEnvBlock(input: {
+ controllerName: string
+ parentControllerUrl: string
+ token: string
+ dashboardPort: number
+ terminalPort: number
+ openclawUrl: string
+ openshellGateway: string
+}) {
+ const registry = JSON.stringify({
+ nodes: [
+ {
+ id: input.controllerName,
+ name: input.controllerName,
+ url: `http://127.0.0.1:${input.dashboardPort}`,
+ role: "controller-node",
+ },
+ ],
+ })
+
+ return [
+ `CONTROLLER_NODE_ID=${input.controllerName}`,
+ `CONTROLLER_NODE_PARENT_URL=${input.parentControllerUrl}`,
+ `CONTROLLER_NODE_SHARED_SECRET=${input.token}`,
+ `NEXT_PUBLIC_DASHBOARD_PORT=${input.dashboardPort}`,
+ "NEXT_PUBLIC_API_BASE=",
+ "NEXT_PUBLIC_ENABLE_SANDBOX_OPERATIONS=true",
+ `OPENSHELL_GATEWAY=${input.openshellGateway}`,
+ "OPEN_SHELL_CONTAINER=openshell-control",
+ "TERMINAL_SERVER_AUTOSTART=true",
+ `TERMINAL_SERVER_PORT=${input.terminalPort}`,
+ `OPENCLAW_DASHBOARD_URL=${input.openclawUrl}`,
+ `OPENCLAW_INSTANCE_REGISTRY_JSON=${registry}`,
+ ].join("\n")
+}
+
+function serviceUnit(installDir: string) {
+ return `[Unit]
+Description=OpenShell Controller Node
+After=network-online.target
+Wants=network-online.target
+
+[Service]
+Type=simple
+WorkingDirectory=${installDir}
+EnvironmentFile=${installDir}/.env.local
+ExecStart=/usr/bin/npm run start
+Restart=always
+RestartSec=5
+User=root
+
+[Install]
+WantedBy=multi-user.target
+`
+}
+
+export function buildControllerNodePlan(input: ControllerPlanRequest = {}): ControllerNodePlan {
+ const controllerName = text(input.controllerName, "remote-controller-01").toLowerCase()
+ if (!SAFE_NAME.test(controllerName)) throw new Error("controllerName must be 2-63 letters, numbers, or hyphens")
+
+ const host = text(input.controllerHost)
+ if (!host || !SAFE_HOST.test(host)) throw new Error("controllerHost must be a hostname or IP address")
+
+ const installDir = validateInstallDir(text(input.installDir, "/opt/openshell-control"))
+ const repoUrl = validateUrl(text(input.repoUrl, DEFAULT_REPO_URL), "repoUrl")
+ const dashboardPort = numberValue(input.dashboardPort, 3000)
+ const terminalPort = numberValue(input.terminalPort, 3011)
+ const openclawUrl = validateHttpUrl(text(input.openclawUrl, text(input.openClawDashboardUrl, "http://localhost:3002")), "openclawUrl")
+ const openshellGateway = text(input.openshellGateway, "local")
+ if (!/^[a-z0-9._:-]+$/i.test(openshellGateway)) throw new Error("openshellGateway contains unsupported characters")
+ const parentControllerUrl = validateHttpUrl(text(input.parentControllerUrl, "http://localhost:3000"), "parentControllerUrl")
+ const token = controllerToken(input.existingToken)
+ const sshTarget = text(input.sshTarget, host)
+ if (!SAFE_SSH_TARGET.test(sshTarget)) throw new Error("sshTarget must look like user@host or user@host:port")
+ const envBlock = buildEnvBlock({
+ controllerName,
+ parentControllerUrl,
+ token,
+ dashboardPort,
+ terminalPort,
+ openclawUrl,
+ openshellGateway,
+ })
+ const unit = serviceUnit(installDir)
+ const remoteBootstrap = `#!/usr/bin/env bash
+set -euo pipefail
+
+INSTALL_DIR=${shellSingleQuote(installDir)}
+REPO_URL=${shellSingleQuote(repoUrl)}
+DASHBOARD_PORT=${dashboardPort}
+TERMINAL_PORT=${terminalPort}
+
+for binary in git node npm; do
+ if ! command -v "$binary" >/dev/null 2>&1; then
+ echo "Missing required binary: $binary" >&2
+ echo "Install Node.js 20+, npm, and git before running this bootstrap." >&2
+ exit 1
+ fi
+done
+
+mkdir -p "$(dirname "$INSTALL_DIR")"
+if [ -d "$INSTALL_DIR/.git" ]; then
+ git -C "$INSTALL_DIR" fetch --depth=1 origin
+ git -C "$INSTALL_DIR" pull --ff-only
+else
+ git clone --depth=1 "$REPO_URL" "$INSTALL_DIR"
+fi
+
+cd "$INSTALL_DIR"
+./install.sh --no-build --no-audit
+
+cat > .env.controller-node <<'ENV_CONTROLLER_NODE'
+${envBlock}
+ENV_CONTROLLER_NODE
+
+touch .env.local
+TMP_ENV="$(mktemp)"
+grep -Ev '^(CONTROLLER_NODE_ID|CONTROLLER_NODE_PARENT_URL|CONTROLLER_NODE_SHARED_SECRET|NEXT_PUBLIC_DASHBOARD_PORT|NEXT_PUBLIC_API_BASE|NEXT_PUBLIC_ENABLE_SANDBOX_OPERATIONS|OPENSHELL_GATEWAY|OPEN_SHELL_CONTAINER|TERMINAL_SERVER_AUTOSTART|TERMINAL_SERVER_PORT|OPENCLAW_DASHBOARD_URL|OPENCLAW_INSTANCE_REGISTRY_JSON)=' .env.local > "$TMP_ENV" || true
+cat "$TMP_ENV" .env.controller-node > .env.local
+rm -f "$TMP_ENV"
+chmod 600 .env.local .env.controller-node
+
+npm run build
+
+if command -v systemctl >/dev/null 2>&1 && [ -w /etc/systemd/system ]; then
+ cat > /etc/systemd/system/openshell-controller-node.service <<'SYSTEMD'
+${unit}
+SYSTEMD
+ systemctl daemon-reload
+ systemctl enable --now openshell-controller-node.service
+ systemctl restart openshell-controller-node.service
+else
+ echo "Systemd service was not installed. Start manually with: npm run start -- --hostname 0.0.0.0 --port $DASHBOARD_PORT"
+fi
+
+echo "Controller node ready at http://${host}:$DASHBOARD_PORT"
+echo "OpenShell CLI is installed in $INSTALL_DIR and can manage sandboxes reachable from this VPS."
+`
+
+ return {
+ controller: {
+ name: controllerName,
+ host,
+ url: `http://${host}:${dashboardPort}`,
+ sshTarget,
+ installDir,
+ repoUrl,
+ parentControllerUrl,
+ dashboardPort,
+ terminalPort,
+ },
+ env: envBlock,
+ serviceUnit: unit,
+ commands: {
+ ssh: `${sshBootstrapInvocation(sshTarget)} 'bash -s' <<'REMOTE_CONTROLLER'\n${remoteBootstrap}\nREMOTE_CONTROLLER`,
+ localBootstrap: remoteBootstrap,
+ start: `cd ${shellSingleQuote(installDir)} && npm run start -- --hostname 0.0.0.0 --port ${dashboardPort}`,
+ terminal: `TERMINAL_SERVER_PORT=${terminalPort} npm run terminal-server`,
+ },
+ checks: [
+ `curl -fsS http://${host}:${dashboardPort}/api/controller-node/health`,
+ `curl -fsS ${openclawUrl}/api/instances`,
+ `ssh ${host} 'cd ${shellSingleQuote(installDir)} && npm run status'`,
+ ],
+ }
+}
diff --git a/app/lib/controllerNodeRegistry.ts b/app/lib/controllerNodeRegistry.ts
new file mode 100644
index 0000000..a1672b5
--- /dev/null
+++ b/app/lib/controllerNodeRegistry.ts
@@ -0,0 +1,156 @@
+import { mkdir, readFile, writeFile } from "node:fs/promises"
+import { hostname } from "node:os"
+import path from "node:path"
+
+export type ControllerNodeRecord = {
+ id: string
+ name: string
+ host: string
+ url: string
+ role: "local" | "controller-node"
+ status: "configured" | "local"
+ updatedAt: string
+}
+
+type StoreShape = {
+ nodes: Record
+}
+
+const STORE_DIR = process.env.OPENSHELL_CONTROL_STATE_DIR || path.join(process.cwd(), ".runtime")
+const STORE_PATH = path.join(STORE_DIR, "controller-nodes.json")
+const SAFE_ID = /^[a-z0-9][a-z0-9._:-]{0,127}$/i
+
+function now() {
+ return new Date().toISOString()
+}
+
+function text(value: unknown, fallback = "") {
+ return typeof value === "string" && value.trim() ? value.trim() : fallback
+}
+
+function slugify(value: string) {
+ return value
+ .trim()
+ .toLowerCase()
+ .replace(/[^a-z0-9._:-]+/g, "-")
+ .replace(/^-+|-+$/g, "")
+ .slice(0, 128)
+}
+
+function localControllerNode(): ControllerNodeRecord {
+ const port = process.env.NEXT_PUBLIC_DASHBOARD_PORT || process.env.PORT || "3000"
+ const url = process.env.OPENSHELL_CONTROL_PUBLIC_URL || `http://localhost:${port}`
+ return {
+ id: "local",
+ name: process.env.OPENSHELL_CONTROL_FRIENDLY_NAME || "Local Controller",
+ host: hostname(),
+ url,
+ role: "local",
+ status: "local",
+ updatedAt: now(),
+ }
+}
+
+function emptyStore(): StoreShape {
+ return { nodes: {} }
+}
+
+function normalizeNode(input: Partial, existing?: ControllerNodeRecord | null): ControllerNodeRecord {
+ const host = text(input.host, existing?.host || "")
+ const url = text(input.url, existing?.url || (host ? `http://${host}:3000` : ""))
+ const id = slugify(text(input.id, existing?.id || host || url))
+ if (!id || !SAFE_ID.test(id)) throw new Error("controller node id is invalid")
+ if (!host) throw new Error("controller node host is required")
+ if (!url) throw new Error("controller node url is required")
+
+ return {
+ id,
+ name: text(input.name, existing?.name || host),
+ host,
+ url,
+ role: input.role === "local" ? "local" : "controller-node",
+ status: input.status === "local" ? "local" : "configured",
+ updatedAt: now(),
+ }
+}
+
+function parseEnvNodes() {
+ const raw = process.env.OPENSHELL_CONTROLLER_NODES_JSON || process.env.OPENCLAW_INSTANCE_REGISTRY_JSON
+ if (!raw?.trim()) return []
+
+ try {
+ const parsed = JSON.parse(raw)
+ const entries = Array.isArray(parsed) ? parsed : Array.isArray(parsed?.nodes) ? parsed.nodes : []
+ return entries
+ .map((entry: unknown) => {
+ if (!entry || typeof entry !== "object") return null
+ const record = entry as Record
+ const url = text(record.url, text(record.controlUiOrigin, text(record.dashboardUrl)))
+ const host = text(record.host, url ? new URL(url).hostname : "")
+ if (!host || !url) return null
+ return normalizeNode({
+ id: text(record.id, host),
+ name: text(record.name, text(record.label, host)),
+ host,
+ url,
+ role: record.role === "local" ? "local" : "controller-node",
+ })
+ })
+ .filter((entry: ControllerNodeRecord | null): entry is ControllerNodeRecord => Boolean(entry))
+ } catch {
+ return []
+ }
+}
+
+async function readStore(): Promise {
+ try {
+ const raw = await readFile(STORE_PATH, "utf8")
+ const parsed = JSON.parse(raw)
+ if (!parsed || typeof parsed !== "object" || !parsed.nodes || typeof parsed.nodes !== "object") return emptyStore()
+ return { nodes: parsed.nodes }
+ } catch {
+ return emptyStore()
+ }
+}
+
+async function writeStore(store: StoreShape) {
+ await mkdir(STORE_DIR, { recursive: true, mode: 0o700 })
+ await writeFile(STORE_PATH, JSON.stringify(store, null, 2), { mode: 0o600 })
+}
+
+export async function listControllerNodes() {
+ const store = await readStore()
+ const merged = new Map()
+ const local = localControllerNode()
+ merged.set(local.id, { ...local, ...store.nodes[local.id], role: "local", status: "local" })
+
+ for (const node of parseEnvNodes()) {
+ merged.set(node.id, { ...node, ...store.nodes[node.id] })
+ }
+ for (const node of Object.values(store.nodes)) {
+ merged.set(node.id, node)
+ }
+
+ return Array.from(merged.values()).sort((a, b) => {
+ if (a.role === "local") return -1
+ if (b.role === "local") return 1
+ return a.name.localeCompare(b.name)
+ })
+}
+
+export async function upsertControllerNode(input: Partial) {
+ const store = await readStore()
+ const id = slugify(text(input.id, input.host || input.url || ""))
+ const existing = id ? store.nodes[id] : null
+ const node = normalizeNode(input, existing)
+ store.nodes[node.id] = node
+ await writeStore(store)
+ return node
+}
+
+export async function renameControllerNode(nodeId: string, name: string) {
+ const nodes = await listControllerNodes()
+ const existing = nodes.find((node) => node.id === slugify(nodeId))
+ if (!existing) throw new Error("controller node was not found")
+ return upsertControllerNode({ ...existing, name })
+}
diff --git a/app/lib/openapiSpec.ts b/app/lib/openapiSpec.ts
new file mode 100644
index 0000000..ac22b2e
--- /dev/null
+++ b/app/lib/openapiSpec.ts
@@ -0,0 +1,361 @@
+export function buildOpenApiSpec(baseUrl = "") {
+ const serverUrl = baseUrl || "http://localhost:3000"
+
+ return {
+ openapi: "3.1.0",
+ info: {
+ title: "OpenShell Control API",
+ version: "0.1.0",
+ description: "Controller-node deployment and registry APIs for OpenShell Control.",
+ },
+ servers: [
+ {
+ url: serverUrl,
+ description: "Current OpenShell Control instance",
+ },
+ ],
+ security: [{ sessionCookie: [] }],
+ tags: [
+ {
+ name: "Controller Nodes",
+ description: "Plan, deploy, register, and rename remote OpenShell Control controller nodes.",
+ },
+ ],
+ paths: {
+ "/api/controller-node/plan": {
+ post: {
+ tags: ["Controller Nodes"],
+ summary: "Generate a remote controller-node launch kit",
+ description: "Builds a bootstrap script, environment block, systemd unit, and readiness checks for a remote controller node. The generated node is also registered locally.",
+ operationId: "createControllerNodePlan",
+ requestBody: {
+ required: true,
+ content: {
+ "application/json": {
+ schema: { $ref: "#/components/schemas/ControllerPlanRequest" },
+ examples: {
+ manual: {
+ summary: "Manual deploy plan",
+ value: {
+ controllerName: "remote-controller-01",
+ controllerHost: "203.0.113.10",
+ sshTarget: "ubuntu@203.0.113.10",
+ installDir: "/opt/openshell-control",
+ repoUrl: "https://github.com/mmckeen-nv/openshell_controller.git",
+ dashboardPort: 3000,
+ terminalPort: 3011,
+ openClawDashboardUrl: "http://127.0.0.1:18789/",
+ openshellGateway: "nemoclaw",
+ parentControllerUrl: "http://localhost:3100",
+ },
+ },
+ },
+ },
+ },
+ },
+ responses: {
+ "200": {
+ description: "Launch kit generated",
+ content: {
+ "application/json": {
+ schema: { $ref: "#/components/schemas/ControllerPlanResponse" },
+ },
+ },
+ },
+ "400": { $ref: "#/components/responses/BadRequest" },
+ "401": { $ref: "#/components/responses/Unauthorized" },
+ },
+ },
+ },
+ "/api/controller-node/deploy": {
+ post: {
+ tags: ["Controller Nodes"],
+ summary: "Autodeploy a controller node over SSH",
+ description: "Connects to a VPS over SSH, optionally elevates with sudo, runs the generated bootstrap, and registers the node locally. The remote password is used once and is not persisted.",
+ operationId: "autodeployControllerNode",
+ requestBody: {
+ required: true,
+ content: {
+ "application/json": {
+ schema: { $ref: "#/components/schemas/ControllerDeployRequest" },
+ examples: {
+ sudo: {
+ summary: "Autodeploy with sudo and pinned host key",
+ value: {
+ controllerName: "remote-controller-01",
+ controllerHost: "203.0.113.10",
+ parentControllerUrl: "http://localhost:3100",
+ remoteHost: "203.0.113.10",
+ remotePort: 22,
+ remoteUser: "ubuntu",
+ remotePassword: "one-time-password",
+ allowSudo: true,
+ expectedHostKeySha256: "SHA256:replace-with-remote-host-fingerprint",
+ },
+ },
+ },
+ },
+ },
+ },
+ responses: {
+ "200": {
+ description: "Remote deploy completed",
+ content: {
+ "application/json": {
+ schema: { $ref: "#/components/schemas/ControllerDeployResponse" },
+ },
+ },
+ },
+ "400": { $ref: "#/components/responses/BadRequest" },
+ "401": { $ref: "#/components/responses/Unauthorized" },
+ },
+ },
+ },
+ "/api/controller-node/registry": {
+ get: {
+ tags: ["Controller Nodes"],
+ summary: "List managed controller nodes",
+ operationId: "listControllerNodes",
+ responses: {
+ "200": {
+ description: "Managed nodes",
+ content: {
+ "application/json": {
+ schema: {
+ type: "object",
+ properties: {
+ nodes: {
+ type: "array",
+ items: { $ref: "#/components/schemas/ControllerNode" },
+ },
+ },
+ required: ["nodes"],
+ },
+ },
+ },
+ },
+ "401": { $ref: "#/components/responses/Unauthorized" },
+ },
+ },
+ post: {
+ tags: ["Controller Nodes"],
+ summary: "Register or rename a controller node",
+ description: "Upserts a controller node, or renames an existing node when action is rename.",
+ operationId: "updateControllerNodeRegistry",
+ requestBody: {
+ required: true,
+ content: {
+ "application/json": {
+ schema: { $ref: "#/components/schemas/ControllerRegistryRequest" },
+ examples: {
+ rename: {
+ summary: "Rename a node",
+ value: {
+ action: "rename",
+ nodeId: "remote-controller-01",
+ name: "Lab VPS East",
+ },
+ },
+ },
+ },
+ },
+ },
+ responses: {
+ "200": {
+ description: "Registry updated",
+ content: {
+ "application/json": {
+ schema: {
+ type: "object",
+ properties: {
+ node: { $ref: "#/components/schemas/ControllerNode" },
+ nodes: {
+ type: "array",
+ items: { $ref: "#/components/schemas/ControllerNode" },
+ },
+ },
+ required: ["node", "nodes"],
+ },
+ },
+ },
+ },
+ "400": { $ref: "#/components/responses/BadRequest" },
+ "401": { $ref: "#/components/responses/Unauthorized" },
+ },
+ },
+ },
+ "/api/openapi": {
+ get: {
+ tags: ["Controller Nodes"],
+ summary: "Fetch the OpenAPI document",
+ operationId: "getOpenApiSpec",
+ responses: {
+ "200": {
+ description: "OpenAPI 3.1 document",
+ content: {
+ "application/json": {
+ schema: {
+ type: "object",
+ additionalProperties: true,
+ },
+ },
+ },
+ },
+ },
+ },
+ },
+ },
+ components: {
+ securitySchemes: {
+ sessionCookie: {
+ type: "apiKey",
+ in: "cookie",
+ name: process.env.OPENSHELL_CONTROL_COOKIE_NAME || "openshell_control_session",
+ },
+ },
+ responses: {
+ BadRequest: {
+ description: "Invalid request",
+ content: {
+ "application/json": {
+ schema: { $ref: "#/components/schemas/ErrorResponse" },
+ },
+ },
+ },
+ Unauthorized: {
+ description: "Authentication required",
+ content: {
+ "application/json": {
+ schema: { $ref: "#/components/schemas/ErrorResponse" },
+ },
+ },
+ },
+ },
+ schemas: {
+ ErrorResponse: {
+ type: "object",
+ properties: {
+ ok: { type: "boolean", example: false },
+ error: { type: "string" },
+ },
+ required: ["error"],
+ },
+ ControllerNode: {
+ type: "object",
+ properties: {
+ id: { type: "string", example: "remote-controller-01" },
+ name: { type: "string", example: "Lab VPS East" },
+ host: { type: "string", example: "203.0.113.10" },
+ url: { type: "string", format: "uri", example: "http://203.0.113.10:3000" },
+ role: { type: "string", enum: ["local", "controller-node"] },
+ status: { type: "string", enum: ["local", "configured"] },
+ updatedAt: { type: "string", format: "date-time" },
+ },
+ required: ["id", "name", "host", "url", "role", "status", "updatedAt"],
+ },
+ ControllerPlanRequest: {
+ type: "object",
+ properties: {
+ controllerName: { type: "string", example: "remote-controller-01" },
+ controllerHost: { type: "string", example: "203.0.113.10" },
+ sshTarget: { type: "string", example: "ubuntu@203.0.113.10" },
+ installDir: { type: "string", example: "/opt/openshell-control" },
+ repoUrl: { type: "string", example: "https://github.com/mmckeen-nv/openshell_controller.git" },
+ dashboardPort: { type: "integer", minimum: 1, maximum: 65535, example: 3000 },
+ terminalPort: { type: "integer", minimum: 1, maximum: 65535, example: 3011 },
+ openClawDashboardUrl: { type: "string", format: "uri", example: "http://127.0.0.1:18789/" },
+ openshellGateway: { type: "string", example: "nemoclaw" },
+ parentControllerUrl: { type: "string", format: "uri", example: "http://localhost:3100" },
+ existingToken: { type: "string", description: "Optional existing controller shared secret." },
+ },
+ required: ["controllerHost"],
+ },
+ ControllerDeployRequest: {
+ allOf: [
+ { $ref: "#/components/schemas/ControllerPlanRequest" },
+ {
+ type: "object",
+ properties: {
+ remoteHost: { type: "string", example: "203.0.113.10" },
+ remotePort: { type: "integer", minimum: 1, maximum: 65535, example: 22 },
+ remoteUser: { type: "string", example: "ubuntu" },
+ remotePassword: { type: "string", format: "password" },
+ allowSudo: { type: "boolean", default: false },
+ acceptUnknownHostKey: { type: "boolean", default: false },
+ expectedHostKeySha256: { type: "string", example: "SHA256:replace-with-remote-host-fingerprint" },
+ },
+ required: ["remoteUser", "remotePassword"],
+ },
+ ],
+ },
+ ControllerPlanResponse: {
+ type: "object",
+ properties: {
+ ok: { type: "boolean", example: true },
+ controller: {
+ type: "object",
+ additionalProperties: true,
+ },
+ env: { type: "string" },
+ serviceUnit: { type: "string" },
+ commands: {
+ type: "object",
+ properties: {
+ ssh: { type: "string" },
+ localBootstrap: { type: "string" },
+ start: { type: "string" },
+ terminal: { type: "string" },
+ },
+ required: ["ssh", "localBootstrap", "start", "terminal"],
+ },
+ checks: {
+ type: "array",
+ items: { type: "string" },
+ },
+ },
+ required: ["ok", "controller", "env", "serviceUnit", "commands", "checks"],
+ },
+ ControllerDeployResponse: {
+ allOf: [
+ { $ref: "#/components/schemas/ControllerPlanResponse" },
+ {
+ type: "object",
+ properties: {
+ hostKeySha256: { type: ["string", "null"] },
+ stdout: { type: "string" },
+ stderr: { type: "string" },
+ note: { type: "string" },
+ },
+ required: ["hostKeySha256", "stdout", "stderr", "note"],
+ },
+ ],
+ },
+ ControllerRegistryRequest: {
+ oneOf: [
+ {
+ type: "object",
+ properties: {
+ action: { type: "string", const: "rename" },
+ nodeId: { type: "string" },
+ name: { type: "string" },
+ },
+ required: ["action", "nodeId", "name"],
+ },
+ {
+ type: "object",
+ properties: {
+ action: { type: "string", const: "upsert" },
+ id: { type: "string" },
+ name: { type: "string" },
+ host: { type: "string" },
+ url: { type: "string", format: "uri" },
+ role: { type: "string", enum: ["local", "controller-node"] },
+ },
+ required: ["host", "url"],
+ },
+ ],
+ },
+ },
+ },
+ }
+}
diff --git a/app/swagger/page.tsx b/app/swagger/page.tsx
new file mode 100644
index 0000000..affa689
--- /dev/null
+++ b/app/swagger/page.tsx
@@ -0,0 +1,114 @@
+import Link from "next/link"
+import { buildOpenApiSpec } from "@/app/lib/openapiSpec"
+
+type OpenApiSpec = ReturnType
+
+function methodClass(method: string) {
+ const normalized = method.toLowerCase()
+ if (normalized === "get") return "border-blue-500/40 bg-blue-500/10 text-blue-300"
+ if (normalized === "post") return "border-[var(--nvidia-green)]/50 bg-[var(--nvidia-green)]/10 text-[var(--nvidia-green)]"
+ return "border-[var(--border-subtle)] bg-[var(--background-tertiary)] text-[var(--foreground-dim)]"
+}
+
+function operationRows(spec: OpenApiSpec) {
+ return Object.entries(spec.paths).flatMap(([path, methods]) =>
+ Object.entries(methods).map(([method, operation]) => ({
+ path,
+ method,
+ operation,
+ })),
+ )
+}
+
+export default function SwaggerPage() {
+ const spec = buildOpenApiSpec()
+ const rows = operationRows(spec)
+
+ return (
+
+
+
+
+
+
OpenAPI 3.1
+
Swagger
+
+ Controller-node API reference for generating launch kits, autodeploying remote nodes, and managing friendly names.
+
+
+
+
+
+
+
+
+
Title
+
{spec.info.title}
+
+
+
Version
+
{spec.info.version}
+
+
+
Auth
+
session cookie
+
+
+
+
+
+
Endpoints
+
Expandable operations generated from the local OpenAPI spec.
+
+
+ {rows.map(({ path, method, operation }) => (
+
+
+
+
+ {method}
+
+ {path}
+
+ {operation.summary}
+
+
+
{operation.description || operation.summary}
+
+
+
Operation
+
{JSON.stringify(operation, null, 2)}
+
+
+
Curl
+
{`${method.toUpperCase()} ${path}\nContent-Type: application/json\nCookie: ${spec.components.securitySchemes.sessionCookie.name}=...`}
+
+
+
+
+ ))}
+
+
+
+
+ Schemas
+
+ {Object.entries(spec.components.schemas).map(([name, schema]) => (
+
+ {name}
+ {JSON.stringify(schema, null, 2)}
+
+ ))}
+
+
+
+
+ )
+}
diff --git a/next.config.mjs b/next.config.mjs
index fb438d1..a176c57 100644
--- a/next.config.mjs
+++ b/next.config.mjs
@@ -1,4 +1,6 @@
/** @type {import('next').NextConfig} */
-const nextConfig = {}
+const nextConfig = {
+ serverExternalPackages: ["ssh2"],
+}
-export default nextConfig
\ No newline at end of file
+export default nextConfig
diff --git a/package-lock.json b/package-lock.json
index 61b85ef..889a6e6 100644
--- a/package-lock.json
+++ b/package-lock.json
@@ -15,6 +15,7 @@
"react": "^18.3.1",
"react-dom": "^18.3.1",
"react-use": "^17.5.0",
+ "ssh2": "^1.17.0",
"ws": "^8.20.0",
"xterm": "^5.3.0",
"xterm-addon-fit": "^0.8.0",
@@ -25,6 +26,7 @@
"@types/node": "^20.16.13",
"@types/react": "^18.3.11",
"@types/react-dom": "^18.3.1",
+ "@types/ssh2": "^1.15.5",
"autoprefixer": "^10.4.20",
"eslint": "^8.57.1",
"eslint-config-next": "^15.5.15",
@@ -1040,6 +1042,33 @@
"@types/react": "^18.0.0"
}
},
+ "node_modules/@types/ssh2": {
+ "version": "1.15.5",
+ "resolved": "https://registry.npmjs.org/@types/ssh2/-/ssh2-1.15.5.tgz",
+ "integrity": "sha512-N1ASjp/nXH3ovBHddRJpli4ozpk6UdDYIX4RJWFa9L1YKnzdhTlVmiGHm4DZnj/jLbqZpes4aeR30EFGQtvhQQ==",
+ "dev": true,
+ "license": "MIT",
+ "dependencies": {
+ "@types/node": "^18.11.18"
+ }
+ },
+ "node_modules/@types/ssh2/node_modules/@types/node": {
+ "version": "18.19.130",
+ "resolved": "https://registry.npmjs.org/@types/node/-/node-18.19.130.tgz",
+ "integrity": "sha512-GRaXQx6jGfL8sKfaIDD6OupbIHBr9jv7Jnaml9tB7l4v068PAOXqfcujMMo5PhbIs6ggR1XODELqahT2R8v0fg==",
+ "dev": true,
+ "license": "MIT",
+ "dependencies": {
+ "undici-types": "~5.26.4"
+ }
+ },
+ "node_modules/@types/ssh2/node_modules/undici-types": {
+ "version": "5.26.5",
+ "resolved": "https://registry.npmjs.org/undici-types/-/undici-types-5.26.5.tgz",
+ "integrity": "sha512-JlCMO+ehdEIKqlFxk6IfVoAUVmgz7cU7zD/h9XZ0qzeosSHmUJVOzSQvvYSYWXkFXC+IfLKSIffhv0sVZup6pA==",
+ "dev": true,
+ "license": "MIT"
+ },
"node_modules/@typescript-eslint/eslint-plugin": {
"version": "8.58.0",
"resolved": "https://registry.npmjs.org/@typescript-eslint/eslint-plugin/-/eslint-plugin-8.58.0.tgz",
@@ -1711,6 +1740,15 @@
"url": "https://github.com/sponsors/ljharb"
}
},
+ "node_modules/asn1": {
+ "version": "0.2.6",
+ "resolved": "https://registry.npmjs.org/asn1/-/asn1-0.2.6.tgz",
+ "integrity": "sha512-ix/FxPn0MDjeyJ7i/yoHGFt/EX6LyNbxSEhPPXODPL+KB0VPk86UYfL0lMdy+KCnv+fmvIzySwaK5COwqVbWTQ==",
+ "license": "MIT",
+ "dependencies": {
+ "safer-buffer": "~2.1.0"
+ }
+ },
"node_modules/ast-types-flow": {
"version": "0.0.8",
"resolved": "https://registry.npmjs.org/ast-types-flow/-/ast-types-flow-0.0.8.tgz",
@@ -1838,6 +1876,15 @@
"node": ">=6.0.0"
}
},
+ "node_modules/bcrypt-pbkdf": {
+ "version": "1.0.2",
+ "resolved": "https://registry.npmjs.org/bcrypt-pbkdf/-/bcrypt-pbkdf-1.0.2.tgz",
+ "integrity": "sha512-qeFIXtP4MSoi6NLqO12WfqARWWuCKi2Rn/9hJLEmtB5yTNr9DqFWkJRCf2qShWzPeAMRnOgCrq0sg/KLv5ES9w==",
+ "license": "BSD-3-Clause",
+ "dependencies": {
+ "tweetnacl": "^0.14.3"
+ }
+ },
"node_modules/binary-extensions": {
"version": "2.3.0",
"resolved": "https://registry.npmjs.org/binary-extensions/-/binary-extensions-2.3.0.tgz",
@@ -1933,6 +1980,15 @@
"node": "^6 || ^7 || ^8 || ^9 || ^10 || ^11 || ^12 || >=13.7"
}
},
+ "node_modules/buildcheck": {
+ "version": "0.0.7",
+ "resolved": "https://registry.npmjs.org/buildcheck/-/buildcheck-0.0.7.tgz",
+ "integrity": "sha512-lHblz4ahamxpTmnsk+MNTRWsjYKv965MwOrSJyeD588rR3Jcu7swE+0wN5F+PbL5cjgu/9ObkhfzEPuofEMwLA==",
+ "optional": true,
+ "engines": {
+ "node": ">=10.0.0"
+ }
+ },
"node_modules/bytes": {
"version": "3.1.2",
"resolved": "https://registry.npmjs.org/bytes/-/bytes-3.1.2.tgz",
@@ -2206,6 +2262,20 @@
"url": "https://opencollective.com/express"
}
},
+ "node_modules/cpu-features": {
+ "version": "0.0.10",
+ "resolved": "https://registry.npmjs.org/cpu-features/-/cpu-features-0.0.10.tgz",
+ "integrity": "sha512-9IkYqtX3YHPCzoVg1Py+o9057a3i0fp7S530UWokCSaFVTc7CwXPRiOjRjBQQ18ZCNafx78YfnG+HALxtVmOGA==",
+ "hasInstallScript": true,
+ "optional": true,
+ "dependencies": {
+ "buildcheck": "~0.0.6",
+ "nan": "^2.19.0"
+ },
+ "engines": {
+ "node": ">=10.0.0"
+ }
+ },
"node_modules/cross-spawn": {
"version": "7.0.6",
"resolved": "https://registry.npmjs.org/cross-spawn/-/cross-spawn-7.0.6.tgz",
@@ -4707,6 +4777,13 @@
"thenify-all": "^1.0.0"
}
},
+ "node_modules/nan": {
+ "version": "2.26.2",
+ "resolved": "https://registry.npmjs.org/nan/-/nan-2.26.2.tgz",
+ "integrity": "sha512-0tTvBTYkt3tdGw22nrAy50x7gpbGCCFH3AFcyS5WiUu7Eu4vWlri1woE6qHBSfy11vksDqkiwjOnlR7WV8G1Hw==",
+ "license": "MIT",
+ "optional": true
+ },
"node_modules/nano-css": {
"version": "5.6.2",
"resolved": "https://registry.npmjs.org/nano-css/-/nano-css-5.6.2.tgz",
@@ -5241,7 +5318,6 @@
"version": "8.5.10",
"resolved": "https://registry.npmjs.org/postcss/-/postcss-8.5.10.tgz",
"integrity": "sha512-pMMHxBOZKFU6HgAZ4eyGnwXF/EvPGGqUr0MnZ5+99485wwW41kW91A4LOGxSHhgugZmSChL5AlElNdwlNgcnLQ==",
- "dev": true,
"funding": [
{
"type": "opencollective",
@@ -6212,6 +6288,23 @@
"node": ">=0.10.0"
}
},
+ "node_modules/ssh2": {
+ "version": "1.17.0",
+ "resolved": "https://registry.npmjs.org/ssh2/-/ssh2-1.17.0.tgz",
+ "integrity": "sha512-wPldCk3asibAjQ/kziWQQt1Wh3PgDFpC0XpwclzKcdT1vql6KeYxf5LIt4nlFkUeR8WuphYMKqUA56X4rjbfgQ==",
+ "hasInstallScript": true,
+ "dependencies": {
+ "asn1": "^0.2.6",
+ "bcrypt-pbkdf": "^1.0.2"
+ },
+ "engines": {
+ "node": ">=10.16.0"
+ },
+ "optionalDependencies": {
+ "cpu-features": "~0.0.10",
+ "nan": "^2.23.0"
+ }
+ },
"node_modules/stable-hash": {
"version": "0.0.5",
"resolved": "https://registry.npmjs.org/stable-hash/-/stable-hash-0.0.5.tgz",
@@ -6733,6 +6826,12 @@
"integrity": "sha512-oJFu94HQb+KVduSUQL7wnpmqnfmLsOA/nAh6b6EH0wCEoK0/mPeXU6c3wKDV83MkOuHPRHtSXKKU99IBazS/2w==",
"license": "0BSD"
},
+ "node_modules/tweetnacl": {
+ "version": "0.14.5",
+ "resolved": "https://registry.npmjs.org/tweetnacl/-/tweetnacl-0.14.5.tgz",
+ "integrity": "sha512-KXXFFdAbFXY4geFIwoyNK+f5Z1b7swfXABfL7HXCmoIWMKU3dmS26672A4EeQtDzLKy7SXmfBu51JolvEKwtGA==",
+ "license": "Unlicense"
+ },
"node_modules/type-check": {
"version": "0.4.0",
"resolved": "https://registry.npmjs.org/type-check/-/type-check-0.4.0.tgz",
diff --git a/package.json b/package.json
index a0d0374..37ea0c2 100644
--- a/package.json
+++ b/package.json
@@ -18,6 +18,7 @@
"react": "^18.3.1",
"react-dom": "^18.3.1",
"react-use": "^17.5.0",
+ "ssh2": "^1.17.0",
"ws": "^8.20.0",
"xterm": "^5.3.0",
"xterm-addon-fit": "^0.8.0",
@@ -28,6 +29,7 @@
"@types/node": "^20.16.13",
"@types/react": "^18.3.11",
"@types/react-dom": "^18.3.1",
+ "@types/ssh2": "^1.15.5",
"autoprefixer": "^10.4.20",
"eslint": "^8.57.1",
"eslint-config-next": "^15.5.15",
diff --git a/tests/controller-node-wizard-check.mjs b/tests/controller-node-wizard-check.mjs
new file mode 100644
index 0000000..0857eed
--- /dev/null
+++ b/tests/controller-node-wizard-check.mjs
@@ -0,0 +1,56 @@
+import assert from 'node:assert/strict'
+import { readFile } from 'node:fs/promises'
+import path from 'node:path'
+
+const root = process.cwd()
+
+const [wizardSource, sidebarSource, planRouteSource, deployRouteSource, registryRouteSource, planLibSource, registryLibSource] = await Promise.all([
+ readFile(path.join(root, 'app/components/WizardPanel.tsx'), 'utf8'),
+ readFile(path.join(root, 'app/components/Sidebar.tsx'), 'utf8'),
+ readFile(path.join(root, 'app/api/controller-node/plan/route.ts'), 'utf8'),
+ readFile(path.join(root, 'app/api/controller-node/deploy/route.ts'), 'utf8'),
+ readFile(path.join(root, 'app/api/controller-node/registry/route.ts'), 'utf8'),
+ readFile(path.join(root, 'app/lib/controllerNodePlan.ts'), 'utf8'),
+ readFile(path.join(root, 'app/lib/controllerNodeRegistry.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, /Manual Deploy/, 'wizard must expose manual deploy mode')
+assert.match(wizardSource, /Autodeploy/, 'wizard must expose autodeploy mode')
+assert.match(wizardSource, /\/api\/controller-node\/plan/, 'wizard must call the controller-node plan API')
+assert.match(wizardSource, /\/api\/controller-node\/deploy/, 'wizard must call the controller-node deploy API')
+assert.match(wizardSource, /SSH Password/, 'autodeploy must collect a password for one-time SSH use')
+assert.match(wizardSource, /Allow sudo/, 'autodeploy must require explicit sudo permission')
+assert.match(wizardSource, /Trust first host key/, 'autodeploy must expose explicit host-key trust')
+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(wizardSource, /aria-expanded=\{controllerWizardOpen\}/, 'controller node wizard must render as an accordion')
+assert.match(wizardSource, /aria-expanded=\{cloneWizardOpen\}/, 'clone wizard must render as an accordion')
+
+assert.match(planRouteSource, /buildControllerNodePlan/, 'plan API must use shared controller plan builder')
+assert.match(planRouteSource, /upsertControllerNode/, 'plan API must register generated controller nodes')
+assert.match(planLibSource, /OPENCLAW_INSTANCE_REGISTRY_JSON/, 'plan builder must configure the OpenClaw instance registry')
+assert.match(planLibSource, /CONTROLLER_NODE_PARENT_URL/, 'plan builder must configure parent controller connectivity')
+assert.match(planLibSource, /CONTROLLER_NODE_SHARED_SECRET/, 'plan builder must generate a node shared secret')
+assert.match(planLibSource, /TERMINAL_SERVER_AUTOSTART=true/, 'plan builder must enable the terminal sidecar for controller nodes')
+assert.match(planLibSource, /openshell-controller-node\.service/, 'plan builder must include a production service unit when systemd is available')
+assert.match(planLibSource, /npm run build/, 'plan builder must produce a complete install/build command')
+assert.match(planLibSource, /OpenShell CLI is installed/, 'plan builder must return operational readiness checks')
+assert.match(deployRouteSource, /ssh2/, 'deploy API must use server-side SSH for autodeploy')
+assert.match(deployRouteSource, /remotePassword/, 'deploy API must accept one-time remote password input')
+assert.match(deployRouteSource, /sudo -S/, 'deploy API must support explicit sudo elevation')
+assert.match(deployRouteSource, /expectedHostKeySha256/, 'deploy API must support host-key fingerprint verification')
+assert.match(deployRouteSource, /acceptUnknownHostKey/, 'deploy API must require explicit trust-on-first-deploy')
+assert.match(sidebarSource, /OpenShell Control/, 'sidebar must keep the OpenShell Control header')
+assert.match(sidebarSource, /\/api\/controller-node\/registry/, 'sidebar must load managed controller nodes')
+assert.match(sidebarSource, /Friendly Name/, 'sidebar must allow friendly names for controller nodes')
+assert.match(sidebarSource, /Managed Node/, 'sidebar must expose a managed-node selector')
+assert.match(registryRouteSource, /listControllerNodes/, 'registry API must expose controller nodes')
+assert.match(registryRouteSource, /renameControllerNode/, 'registry API must support friendly-name updates')
+assert.match(registryLibSource, /OPENSHELL_CONTROLLER_NODES_JSON|OPENCLAW_INSTANCE_REGISTRY_JSON/, 'registry must detect configured remote controller nodes')
+assert.doesNotMatch(`${planRouteSource}\n${deployRouteSource}\n${planLibSource}\n${registryLibSource}`, /\/home\/nvidia|\/Users\/markmckeen/, 'controller node code must not bake in developer machine paths')
+
+console.log('controller-node-wizard-check: PASS controller node wizard assertions')
diff --git a/tests/swagger-openapi-check.mjs b/tests/swagger-openapi-check.mjs
new file mode 100644
index 0000000..8e72ba7
--- /dev/null
+++ b/tests/swagger-openapi-check.mjs
@@ -0,0 +1,30 @@
+import assert from 'node:assert/strict'
+import { readFile } from 'node:fs/promises'
+import path from 'node:path'
+
+const root = process.cwd()
+
+const [specSource, routeSource, pageSource, sidebarSource, helpSource] = await Promise.all([
+ readFile(path.join(root, 'app/lib/openapiSpec.ts'), 'utf8'),
+ readFile(path.join(root, 'app/api/openapi/route.ts'), 'utf8'),
+ readFile(path.join(root, 'app/swagger/page.tsx'), 'utf8'),
+ readFile(path.join(root, 'app/components/Sidebar.tsx'), 'utf8'),
+ readFile(path.join(root, 'app/components/HelpPanel.tsx'), 'utf8'),
+])
+
+assert.match(specSource, /openapi:\s*"3\.1\.0"/, 'OpenAPI spec must declare version 3.1.0')
+assert.match(specSource, /\/api\/controller-node\/plan/, 'spec must document controller plan endpoint')
+assert.match(specSource, /\/api\/controller-node\/deploy/, 'spec must document controller deploy endpoint')
+assert.match(specSource, /\/api\/controller-node\/registry/, 'spec must document controller registry endpoint')
+assert.match(specSource, /ControllerDeployRequest/, 'spec must include autodeploy request schema')
+assert.match(specSource, /sessionCookie/, 'spec must document session cookie auth')
+assert.match(routeSource, /buildOpenApiSpec/, 'OpenAPI API route must return generated spec')
+assert.match(pageSource, /OpenAPI JSON/, 'Swagger page must link to the JSON spec')
+assert.match(pageSource, /Endpoints/, 'Swagger page must render endpoint docs')
+assert.match(pageSource, /Schemas/, 'Swagger page must render schema docs')
+assert.doesNotMatch(sidebarSource, /href="\/swagger"/, 'Swagger must not be a top-level sidebar item')
+assert.match(helpSource, /API Reference/, 'Help must expose an API reference section')
+assert.match(helpSource, /href="\/swagger"/, 'Help must link to the Swagger page')
+assert.match(helpSource, /target="_blank"/, 'Help must open Swagger in a separate page')
+
+console.log('swagger-openapi-check: PASS swagger/openapi assertions')