@swarmclawai/swarmclaw 0.7.6 → 0.7.8

package/src/lib/server/openclaw-deploy.ts

@@ -1,13 +1,17 @@
 import { randomBytes } from 'node:crypto'
 import { existsSync } from 'node:fs'
+import { promises as fs } from 'node:fs'
+import os from 'node:os'
 import path from 'node:path'
 import {
   getManagedProcess,
   killManagedProcess,
   removeManagedProcess,
   startManagedProcess,
+  type ProcessStatus,
 } from './process-manager'
 import { normalizeOpenClawEndpoint, deriveOpenClawWsUrl } from '@/lib/openclaw-endpoint'
+import { probeOpenClawHealth, type OpenClawHealthResult } from './openclaw-health'
 
 export type OpenClawRemoteDeployTemplate = 'docker' | 'render' | 'fly' | 'railway'
 export type OpenClawRemoteDeployProvider =
@@ -20,6 +24,8 @@ export type OpenClawRemoteDeployProvider =
   | 'azure'
   | 'oci'
   | 'generic'
+export type OpenClawUseCaseTemplate = 'local-dev' | 'single-vps' | 'private-tailnet' | 'browser-heavy' | 'team-control'
+export type OpenClawExposurePreset = 'private-lan' | 'tailscale' | 'caddy' | 'nginx' | 'ssh-tunnel'
 
 export interface OpenClawLocalDeployStatus {
   running: boolean
@@ -36,6 +42,22 @@ export interface OpenClawLocalDeployStatus {
   installCommand: string
 }
 
+export interface OpenClawRemoteDeployStatus {
+  active: boolean
+  processId: string | null
+  pid: number | null
+  action: string | null
+  target: string | null
+  startedAt: number | null
+  status: ProcessStatus | 'idle'
+  exitCode: number | null
+  tail: string
+  lastError: string | null
+  lastSummary: string | null
+  lastCommandPreview: string | null
+  lastBackupPath: string | null
+}
+
 export interface OpenClawDeployBundleFile {
   name: string
   language: 'bash' | 'yaml' | 'env' | 'toml' | 'text'
@@ -46,6 +68,8 @@ export interface OpenClawDeployBundle {
   template: OpenClawRemoteDeployTemplate
   provider: OpenClawRemoteDeployProvider
   providerLabel: string
+  useCase: OpenClawUseCaseTemplate
+  exposure: OpenClawExposurePreset
   title: string
   summary: string
   endpoint: string
@@ -55,6 +79,24 @@ export interface OpenClawDeployBundle {
   files: OpenClawDeployBundleFile[]
 }
 
+export interface OpenClawSshConfig {
+  host: string
+  user?: string | null
+  port?: number | null
+  keyPath?: string | null
+  targetDir?: string | null
+}
+
+export interface OpenClawRemoteCommandResult {
+  ok: boolean
+  started: boolean
+  processId?: string | null
+  summary: string
+  commandPreview: string
+  token?: string
+  bundle?: OpenClawDeployBundle
+}
+
 interface LocalRuntimeState {
   processId: string | null
   port: number
@@ -65,8 +107,20 @@ interface LocalRuntimeState {
   lastError: string | null
 }
 
+interface RemoteRuntimeState {
+  processId: string | null
+  action: string | null
+  target: string | null
+  startedAt: number | null
+  lastError: string | null
+  lastSummary: string | null
+  lastCommandPreview: string | null
+  lastBackupPath: string | null
+}
+
 interface DeployRuntimeState {
   local: LocalRuntimeState
+  remote: RemoteRuntimeState
 }
 
 interface RemoteProviderMeta {
@@ -77,6 +131,22 @@ interface RemoteProviderMeta {
   summary: string
 }
 
+interface UseCaseMeta {
+  id: OpenClawUseCaseTemplate
+  label: string
+  summary: string
+  detail: string
+  defaultExposure: OpenClawExposurePreset
+  hostBind: string
+  nodeOptions: string | null
+}
+
+interface ExposureMeta {
+  id: OpenClawExposurePreset
+  label: string
+  summary: string
+}
+
 const DEFAULT_LOCAL_PORT = 18789
 const DEFAULT_REMOTE_PORT = 18789
 const GLOBAL_KEY = '__swarmclaw_openclaw_deploy__' as const
@@ -147,6 +217,82 @@ const REMOTE_PROVIDER_META: Record<OpenClawRemoteDeployProvider, RemoteProviderM
   },
 }
 
+const USE_CASE_META: Record<OpenClawUseCaseTemplate, UseCaseMeta> = {
+  'local-dev': {
+    id: 'local-dev',
+    label: 'Local Dev',
+    summary: 'Local-first OpenClaw control plane for testing and personal machines.',
+    detail: 'Binds to loopback with safe defaults so a single developer can stand up OpenClaw quickly.',
+    defaultExposure: 'private-lan',
+    hostBind: '127.0.0.1',
+    nodeOptions: null,
+  },
+  'single-vps': {
+    id: 'single-vps',
+    label: 'Single VPS',
+    summary: 'Balanced always-on control plane for one server and a small swarm.',
+    detail: 'Good default for Hetzner, DigitalOcean, Vultr, Linode, Lightsail, and generic Ubuntu VPS installs.',
+    defaultExposure: 'caddy',
+    hostBind: '0.0.0.0',
+    nodeOptions: null,
+  },
+  'private-tailnet': {
+    id: 'private-tailnet',
+    label: 'Private Tailnet',
+    summary: 'Keep the gateway off the public internet and expose it only through a trusted tailnet.',
+    detail: 'Uses loopback binding and pairs well with Tailscale or an SSH tunnel.',
+    defaultExposure: 'tailscale',
+    hostBind: '127.0.0.1',
+    nodeOptions: null,
+  },
+  'browser-heavy': {
+    id: 'browser-heavy',
+    label: 'Browser Heavy',
+    summary: 'Higher-memory defaults for browser tools and long-running automation nodes.',
+    detail: 'Raises Node memory limits and assumes a roomier VPS profile for browser-backed tasks.',
+    defaultExposure: 'caddy',
+    hostBind: '0.0.0.0',
+    nodeOptions: '--max-old-space-size=3072',
+  },
+  'team-control': {
+    id: 'team-control',
+    label: 'Team Control',
+    summary: 'Shared control plane defaults for a trusted team with backups and cleaner exposure choices.',
+    detail: 'Prioritizes predictable exposure and easier operator handoff across a team.',
+    defaultExposure: 'caddy',
+    hostBind: '0.0.0.0',
+    nodeOptions: '--max-old-space-size=2048',
+  },
+}
+
+const EXPOSURE_META: Record<OpenClawExposurePreset, ExposureMeta> = {
+  'private-lan': {
+    id: 'private-lan',
+    label: 'Private LAN',
+    summary: 'Expose only on your LAN or through provider firewall rules.',
+  },
+  tailscale: {
+    id: 'tailscale',
+    label: 'Tailscale',
+    summary: 'Keep OpenClaw on loopback and publish it only over your Tailscale tailnet.',
+  },
+  caddy: {
+    id: 'caddy',
+    label: 'Caddy',
+    summary: 'Run a bundled reverse proxy that can terminate HTTPS and proxy the gateway safely.',
+  },
+  nginx: {
+    id: 'nginx',
+    label: 'Nginx',
+    summary: 'Use an Nginx reverse proxy for teams that already manage TLS or edge certificates.',
+  },
+  'ssh-tunnel': {
+    id: 'ssh-tunnel',
+    label: 'SSH Tunnel',
+    summary: 'Keep the gateway on loopback and access it through an SSH tunnel when needed.',
+  },
+}
+
 function getRuntimeState(): DeployRuntimeState {
   const fallback: DeployRuntimeState = {
     local: {
@@ -158,6 +304,16 @@ function getRuntimeState(): DeployRuntimeState {
       startedAt: null,
       lastError: null,
     },
+    remote: {
+      processId: null,
+      action: null,
+      target: null,
+      startedAt: null,
+      lastError: null,
+      lastSummary: null,
+      lastCommandPreview: null,
+      lastBackupPath: null,
+    },
   }
   const globalState = globalThis as typeof globalThis & { [GLOBAL_KEY]?: DeployRuntimeState }
   if (!globalState[GLOBAL_KEY]) {
@@ -228,6 +384,10 @@ function normalizeToken(value: unknown): string | null {
   return typeof value === 'string' && value.trim() ? value.trim() : null
 }
 
+function normalizeText(value: unknown): string | null {
+  return typeof value === 'string' && value.trim() ? value.trim() : null
+}
+
 function normalizeRemoteProvider(value: unknown): OpenClawRemoteDeployProvider {
   if (
     value === 'hetzner'
@@ -245,6 +405,147 @@ function normalizeRemoteProvider(value: unknown): OpenClawRemoteDeployProvider {
   return 'hetzner'
 }
 
+function normalizeUseCase(value: unknown): OpenClawUseCaseTemplate {
+  if (
+    value === 'local-dev'
+    || value === 'single-vps'
+    || value === 'private-tailnet'
+    || value === 'browser-heavy'
+    || value === 'team-control'
+  ) {
+    return value
+  }
+  return 'single-vps'
+}
+
+function normalizeExposurePreset(value: unknown, fallback?: OpenClawUseCaseTemplate): OpenClawExposurePreset {
+  if (
+    value === 'private-lan'
+    || value === 'tailscale'
+    || value === 'caddy'
+    || value === 'nginx'
+    || value === 'ssh-tunnel'
+  ) {
+    return value
+  }
+  const useCase = fallback ? USE_CASE_META[fallback] : null
+  return useCase?.defaultExposure || 'private-lan'
+}
+
+function sanitizeSshConfig(input?: Partial<OpenClawSshConfig> | null): OpenClawSshConfig | null {
+  const host = typeof input?.host === 'string' && input.host.trim() ? input.host.trim() : ''
+  if (!host) return null
+  const port = sanitizePort(input?.port, 22)
+  return {
+    host,
+    user: typeof input?.user === 'string' && input.user.trim() ? input.user.trim() : 'root',
+    port,
+    keyPath: typeof input?.keyPath === 'string' && input.keyPath.trim() ? input.keyPath.trim() : null,
+    targetDir: typeof input?.targetDir === 'string' && input.targetDir.trim() ? input.targetDir.trim() : '/opt/openclaw',
+  }
+}
+
+function buildSshTarget(config: OpenClawSshConfig): string {
+  return `${config.user || 'root'}@${config.host}`
+}
+
+function buildSshArgs(config: OpenClawSshConfig, forScp = false): string[] {
+  const args: string[] = ['-o', 'BatchMode=yes', '-o', 'StrictHostKeyChecking=accept-new']
+  if (config.keyPath) args.push('-i', config.keyPath)
+  args.push(forScp ? '-P' : '-p', String(config.port || 22))
+  return args
+}
+
+async function materializeBundleFiles(bundle: OpenClawDeployBundle): Promise<{ dir: string; filePaths: string[] }> {
+  const dir = await fs.mkdtemp(path.join(os.tmpdir(), 'swarmclaw-openclaw-'))
+  const filePaths: string[] = []
+  for (const file of bundle.files) {
+    const filePath = path.join(dir, file.name)
+    await fs.mkdir(path.dirname(filePath), { recursive: true })
+    await fs.writeFile(filePath, file.content, 'utf8')
+    filePaths.push(filePath)
+  }
+  return { dir, filePaths }
+}
+
+function updateRemoteRuntimeState(patch: Partial<RemoteRuntimeState>) {
+  Object.assign(getRuntimeState().remote, patch)
+}
+
+async function startRemoteCommand(params: {
+  action: string
+  target: string
+  command: string
+  summary: string
+  backupPath?: string | null
+}): Promise<OpenClawRemoteCommandResult> {
+  const result = await startManagedProcess({
+    command: params.command,
+    cwd: process.cwd(),
+    background: true,
+    timeoutMs: 30 * 60_000,
+  })
+
+  if (result.status === 'completed' && (result.exitCode ?? 0) === 0) {
+    updateRemoteRuntimeState({
+      processId: null,
+      action: params.action,
+      target: params.target,
+      startedAt: Date.now(),
+      lastError: null,
+      lastSummary: params.summary,
+      lastCommandPreview: params.command,
+      lastBackupPath: params.backupPath || null,
+    })
+    return {
+      ok: true,
+      started: false,
+      processId: null,
+      summary: params.summary,
+      commandPreview: params.command,
+    }
+  }
+
+  if (result.status !== 'running') {
+    const message = result.output || result.tail || params.summary
+    updateRemoteRuntimeState({
+      processId: null,
+      action: params.action,
+      target: params.target,
+      startedAt: null,
+      lastError: message,
+      lastSummary: params.summary,
+      lastCommandPreview: params.command,
+      lastBackupPath: params.backupPath || null,
+    })
+    return {
+      ok: false,
+      started: false,
+      processId: null,
+      summary: message,
+      commandPreview: params.command,
+    }
+  }
+
+  updateRemoteRuntimeState({
+    processId: result.processId,
+    action: params.action,
+    target: params.target,
+    startedAt: Date.now(),
+    lastError: null,
+    lastSummary: params.summary,
+    lastCommandPreview: params.command,
+    lastBackupPath: params.backupPath || null,
+  })
+  return {
+    ok: true,
+    started: true,
+    processId: result.processId,
+    summary: params.summary,
+    commandPreview: params.command,
+  }
+}
+
 function wait(ms: number): Promise<void> {
   return new Promise((resolve) => setTimeout(resolve, ms))
 }
@@ -296,6 +597,38 @@ export function getOpenClawLocalDeployStatus(): OpenClawLocalDeployStatus {
   return currentLocalStatus()
 }
 
+function currentRemoteStatus(): OpenClawRemoteDeployStatus {
+  const state = getRuntimeState()
+  const processId = state.remote.processId
+  const process = processId ? getManagedProcess(processId) : null
+  const active = !!process && process.status === 'running'
+
+  if (!active && processId && process && process.status !== 'running') {
+    state.remote.lastError = readTail(process.log || '') || state.remote.lastError
+    state.remote.processId = null
+  }
+
+  return {
+    active,
+    processId: active ? processId : null,
+    pid: active ? (process?.pid ?? null) : null,
+    action: state.remote.action || null,
+    target: state.remote.target || null,
+    startedAt: state.remote.startedAt || null,
+    status: process?.status || 'idle',
+    exitCode: process?.exitCode ?? null,
+    tail: process ? readTail(process.log || '') : '',
+    lastError: active ? null : (state.remote.lastError || null),
+    lastSummary: state.remote.lastSummary || null,
+    lastCommandPreview: state.remote.lastCommandPreview || null,
+    lastBackupPath: state.remote.lastBackupPath || null,
+  }
+}
+
+export function getOpenClawRemoteDeployStatus(): OpenClawRemoteDeployStatus {
+  return currentRemoteStatus()
+}
+
 export function generateOpenClawGatewayToken(): string {
   return randomBytes(24).toString('base64url')
 }
@@ -387,6 +720,17 @@ export function stopOpenClawLocalDeploy(): OpenClawLocalDeployStatus {
   return currentLocalStatus()
 }
 
+export async function restartOpenClawLocalDeploy(input?: {
+  port?: number
+  token?: string | null
+}): Promise<{ local: OpenClawLocalDeployStatus; token: string }> {
+  const current = currentLocalStatus()
+  return startOpenClawLocalDeploy({
+    port: input?.port ?? current.port,
+    token: input?.token ?? current.token,
+  })
+}
+
 function ensureSchemeAndPort(raw: string, scheme: 'http' | 'https', port: number): string {
   const trimmed = raw.trim()
   if (!trimmed) {
@@ -417,21 +761,36 @@ function indentBlock(value: string, spaces: number): string {
     .join('\n')
 }
 
-function buildDockerComposeFile(): string {
+interface DockerBundleOptions {
+  token: string
+  endpointHost: string
+  useCase: OpenClawUseCaseTemplate
+  exposure: OpenClawExposurePreset
+}
+
+function resolveHostBindAddress(useCase: OpenClawUseCaseTemplate, exposure: OpenClawExposurePreset): string {
+  if (exposure === 'tailscale' || exposure === 'ssh-tunnel' || exposure === 'caddy' || exposure === 'nginx') {
+    return '127.0.0.1'
+  }
+  return USE_CASE_META[useCase].hostBind
+}
+
+function buildDockerComposeFile(options: DockerBundleOptions): string {
   return `services:
   openclaw-gateway:
     image: \${OPENCLAW_IMAGE:-openclaw:latest}
     environment:
       HOME: /home/node
       TERM: xterm-256color
+      NODE_OPTIONS: \${OPENCLAW_NODE_OPTIONS:-}
       OPENCLAW_GATEWAY_TOKEN: \${OPENCLAW_GATEWAY_TOKEN}
       OPENCLAW_GATEWAY_BIND: \${OPENCLAW_GATEWAY_BIND:-lan}
     volumes:
       - \${OPENCLAW_CONFIG_DIR:-./.openclaw}:/home/node/.openclaw
       - \${OPENCLAW_WORKSPACE_DIR:-./workspace}:/home/node/.openclaw/workspace
     ports:
-      - "\${OPENCLAW_GATEWAY_PORT:-18789}:18789"
-      - "\${OPENCLAW_BRIDGE_PORT:-18790}:18790"
+      - "\${OPENCLAW_HOST_BIND:-${resolveHostBindAddress(options.useCase, options.exposure)}}:\${OPENCLAW_GATEWAY_PORT:-18789}:18789"
+      - "\${OPENCLAW_HOST_BIND:-${resolveHostBindAddress(options.useCase, options.exposure)}}:\${OPENCLAW_BRIDGE_PORT:-18790}:18790"
     init: true
     restart: unless-stopped
     command:
@@ -464,18 +823,22 @@ function buildDockerComposeFile(): string {
 `
 }
 
-function buildDockerEnvFile(token: string): string {
+function buildDockerEnvFile(options: DockerBundleOptions): string {
   return `OPENCLAW_IMAGE=openclaw:latest
-OPENCLAW_GATEWAY_TOKEN=${token}
+OPENCLAW_GATEWAY_TOKEN=${options.token}
 OPENCLAW_GATEWAY_BIND=lan
+OPENCLAW_HOST_BIND=${resolveHostBindAddress(options.useCase, options.exposure)}
 OPENCLAW_GATEWAY_PORT=18789
 OPENCLAW_BRIDGE_PORT=18790
 OPENCLAW_CONFIG_DIR=./.openclaw
 OPENCLAW_WORKSPACE_DIR=./workspace
+OPENCLAW_USE_CASE=${options.useCase}
+OPENCLAW_EXPOSURE=${options.exposure}
+OPENCLAW_NODE_OPTIONS=${USE_CASE_META[options.useCase].nodeOptions || ''}
 `
 }
 
-function buildDockerBootstrapScript(): string {
+function buildDockerBootstrapScript(options: DockerBundleOptions): string {
   return `#!/usr/bin/env bash
 set -euo pipefail
 
@@ -483,7 +846,7 @@ APP_DIR="\${OPENCLAW_APP_DIR:-$HOME/openclaw}"
 
 mkdir -p "$APP_DIR"
 cd "$APP_DIR"
-mkdir -p .openclaw workspace
+mkdir -p .openclaw workspace backups
 
 if ! command -v docker >/dev/null 2>&1; then
   echo "Docker is required. On Ubuntu 24.04 you can install it with:"
@@ -493,13 +856,27 @@ fi
 
 docker pull "\${OPENCLAW_IMAGE:-openclaw:latest}"
 docker compose up -d
+if [ -f docker-compose.proxy.yml ]; then
+  docker compose -f docker-compose.yml -f docker-compose.proxy.yml up -d
+fi
 docker compose ps
+echo "Use case: ${options.useCase}"
+echo "Exposure preset: ${options.exposure}"
 `
 }
 
-function buildCloudInitFile(token: string): string {
-  const envFile = buildDockerEnvFile(token)
-  const composeFile = buildDockerComposeFile()
+function buildCloudInitFile(options: DockerBundleOptions): string {
+  const envFile = buildDockerEnvFile(options)
+  const composeFile = buildDockerComposeFile(options)
+  const bootstrapFile = buildDockerBootstrapScript(options)
+  const extraFiles = buildExposureFiles(options)
+    .filter((file) => !['.env', 'docker-compose.yml', 'bootstrap.sh'].includes(file.name))
+    .map((file) => `  - path: /opt/openclaw/${file.name}
+    owner: root:root
+    permissions: "${file.name.endsWith('.sh') ? '0755' : '0644'}"
+    content: |
+${indentBlock(file.content, 6)}`)
+    .join('\n')
   return `#cloud-config
 package_update: true
 package_upgrade: true
@@ -519,15 +896,131 @@ ${indentBlock(envFile, 6)}
     permissions: "0644"
     content: |
 ${indentBlock(composeFile, 6)}
-runcmd:
-  - mkdir -p /opt/openclaw/.openclaw /opt/openclaw/workspace
+  - path: /opt/openclaw/bootstrap.sh
+    owner: root:root
+    permissions: "0755"
+    content: |
+${indentBlock(bootstrapFile, 6)}
+${extraFiles ? `${extraFiles}
+` : ''}runcmd:
+  - mkdir -p /opt/openclaw/.openclaw /opt/openclaw/workspace /opt/openclaw/backups
   - systemctl enable --now docker
   - bash -lc 'cd /opt/openclaw && docker pull "\${OPENCLAW_IMAGE:-openclaw:latest}"'
   - bash -lc 'cd /opt/openclaw && docker compose up -d'
+  - bash -lc 'cd /opt/openclaw && if [ -f docker-compose.proxy.yml ]; then docker compose -f docker-compose.yml -f docker-compose.proxy.yml up -d; fi'
 final_message: "OpenClaw gateway bootstrap complete. Run: sudo docker compose -f /opt/openclaw/docker-compose.yml ps"
 `
 }
 
+function buildCaddyComposeFile(): string {
+  return `services:
+  caddy:
+    image: caddy:2
+    restart: unless-stopped
+    depends_on:
+      - openclaw-gateway
+    ports:
+      - "80:80"
+      - "443:443"
+    volumes:
+      - ./Caddyfile:/etc/caddy/Caddyfile:ro
+      - caddy_data:/data
+      - caddy_config:/config
+
+volumes:
+  caddy_data:
+  caddy_config:
+`
+}
+
+function buildCaddyfile(endpointHost: string): string {
+  return `${endpointHost} {
+  encode gzip
+  reverse_proxy openclaw-gateway:18789
+}
+`
+}
+
+function buildNginxComposeFile(): string {
+  return `services:
+  nginx:
+    image: nginx:1.27-alpine
+    restart: unless-stopped
+    depends_on:
+      - openclaw-gateway
+    ports:
+      - "80:80"
+    volumes:
+      - ./nginx.conf:/etc/nginx/conf.d/default.conf:ro
+`
+}
+
+function buildNginxConfig(endpointHost: string): string {
+  return `server {
+  listen 80;
+  server_name ${endpointHost};
+
+  location / {
+    proxy_pass http://openclaw-gateway:18789;
+    proxy_http_version 1.1;
+    proxy_set_header Host $host;
+    proxy_set_header X-Forwarded-Proto $scheme;
+    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+    proxy_set_header Upgrade $http_upgrade;
+    proxy_set_header Connection "upgrade";
+  }
+}
+`
+}
+
+function buildTailscaleServeScript(): string {
+  return `#!/usr/bin/env bash
+set -euo pipefail
+
+PORT="\${OPENCLAW_GATEWAY_PORT:-18789}"
+if ! command -v tailscale >/dev/null 2>&1; then
+  echo "Install Tailscale first: https://tailscale.com/download"
+  exit 1
+fi
+
+sudo tailscale serve --bg --set-path=/ http://127.0.0.1:$PORT
+tailscale status
+`
+}
+
+function buildSshTunnelGuide(endpointHost: string): string {
+  return `Use an SSH tunnel instead of opening the gateway publicly.
+
+Example:
+  ssh -N -L 18789:127.0.0.1:18789 user@${endpointHost}
+
+Then point SwarmClaw at:
+  http://127.0.0.1:18789/v1
+`
+}
+
+function buildExposureFiles(options: DockerBundleOptions): OpenClawDeployBundleFile[] {
+  if (options.exposure === 'caddy') {
+    return [
+      { name: 'docker-compose.proxy.yml', language: 'yaml', content: buildCaddyComposeFile() },
+      { name: 'Caddyfile', language: 'text', content: buildCaddyfile(options.endpointHost) },
+    ]
+  }
+  if (options.exposure === 'nginx') {
+    return [
+      { name: 'docker-compose.proxy.yml', language: 'yaml', content: buildNginxComposeFile() },
+      { name: 'nginx.conf', language: 'text', content: buildNginxConfig(options.endpointHost) },
+    ]
+  }
+  if (options.exposure === 'tailscale') {
+    return [{ name: 'tailscale-serve.sh', language: 'bash', content: buildTailscaleServeScript() }]
+  }
+  if (options.exposure === 'ssh-tunnel') {
+    return [{ name: 'ssh-tunnel.txt', language: 'text', content: buildSshTunnelGuide(options.endpointHost) }]
+  }
+  return []
+}
+
 function buildRenderManifest(): string {
   return `services:
   - type: web
@@ -610,12 +1103,23 @@ function buildRailwayConfig(): string {
 function buildDockerRunbook(
   providerMeta: RemoteProviderMeta,
   endpoint: string,
+  useCase: OpenClawUseCaseTemplate,
+  exposure: OpenClawExposurePreset,
 ): string[] {
   const endpointHost = deriveRemoteDeploymentName(endpoint)
   return [
     `Provision a small Ubuntu 24.04 server on ${providerMeta.label}. ${providerMeta.bootstrapHint}`,
+    `Use case preset: ${USE_CASE_META[useCase].label}. Exposure preset: ${EXPOSURE_META[exposure].label}.`,
     'Let first boot finish, then confirm the service with: sudo docker compose -f /opt/openclaw/docker-compose.yml ps',
-    `Point a DNS name, reverse proxy, or Tailscale hostname at ${endpointHost} and keep the generated token private.`,
+    exposure === 'tailscale'
+      ? 'Run tailscale-serve.sh after the host joins your tailnet so OpenClaw stays private.'
+      : exposure === 'caddy'
+        ? 'Set your DNS name to this host and start the bundled Caddy proxy for HTTPS termination.'
+        : exposure === 'nginx'
+          ? 'Start the bundled Nginx proxy or bring your own TLS terminator in front of the gateway.'
+          : exposure === 'ssh-tunnel'
+            ? 'Do not expose the gateway publicly; use the generated SSH tunnel guide instead.'
+            : `Point a DNS name, reverse proxy, or private network hostname at ${endpointHost} and keep the generated token private.`,
     'Use the generated endpoint and token in SwarmClaw to save the gateway profile.',
   ]
 }
@@ -627,6 +1131,8 @@ export function buildOpenClawDeployBundle(input?: {
   scheme?: 'http' | 'https'
   port?: number
   provider?: OpenClawRemoteDeployProvider
+  useCase?: OpenClawUseCaseTemplate
+  exposure?: OpenClawExposurePreset
 }): OpenClawDeployBundle {
   const template = input?.template || 'docker'
   const token = normalizeToken(input?.token) || generateOpenClawGatewayToken()
@@ -637,12 +1143,22 @@ export function buildOpenClawDeployBundle(input?: {
   const wsUrl = deriveOpenClawWsUrl(endpoint)
   const provider = normalizeRemoteProvider(input?.provider)
   const providerMeta = REMOTE_PROVIDER_META[provider]
+  const useCase = normalizeUseCase(input?.useCase)
+  const exposure = normalizeExposurePreset(input?.exposure, useCase)
+  const bundleOptions: DockerBundleOptions = {
+    token,
+    endpointHost: deriveRemoteDeploymentName(endpoint),
+    useCase,
+    exposure,
+  }
 
   if (template === 'render') {
     return {
       template,
       provider: 'generic',
       providerLabel: 'Render',
+      useCase,
+      exposure,
       title: 'Render OpenClaw Service',
       summary: 'Deploy the official OpenClaw repo as a Docker web service on Render, then point SwarmClaw at the public HTTPS URL.',
       endpoint,
@@ -665,6 +1181,8 @@ export function buildOpenClawDeployBundle(input?: {
       template,
       provider: 'generic',
       providerLabel: 'Fly.io',
+      useCase,
+      exposure,
       title: 'Fly.io OpenClaw App',
       summary: 'Deploy the official OpenClaw repo on Fly.io for an always-on remote gateway with a persistent volume and HTTPS out of the box.',
       endpoint,
@@ -687,6 +1205,8 @@ export function buildOpenClawDeployBundle(input?: {
       template,
       provider: 'generic',
       providerLabel: 'Railway',
+      useCase,
+      exposure,
       title: 'Railway OpenClaw Service',
       summary: 'Deploy the official OpenClaw repo on Railway using its Dockerfile, then attach a volume and set the generated gateway token.',
       endpoint,
@@ -708,17 +1228,157 @@ export function buildOpenClawDeployBundle(input?: {
     template: 'docker',
     provider,
     providerLabel: providerMeta.shortLabel,
+    useCase,
+    exposure,
     title: `${providerMeta.shortLabel} OpenClaw Smart Deploy`,
-    summary: `${providerMeta.summary} This bundle only uses the official OpenClaw Docker image and gives you both manual Docker files and a cloud-init quickstart.`,
+    summary: `${providerMeta.summary} ${USE_CASE_META[useCase].detail} This bundle only uses the official OpenClaw Docker image and gives you both manual Docker files and a cloud-init quickstart.`,
     endpoint,
     wsUrl,
     token,
-    runbook: buildDockerRunbook(providerMeta, endpoint),
+    runbook: buildDockerRunbook(providerMeta, endpoint, useCase, exposure),
     files: [
-      { name: 'cloud-init.yaml', language: 'yaml', content: buildCloudInitFile(token) },
-      { name: '.env', language: 'env', content: buildDockerEnvFile(token) },
-      { name: 'docker-compose.yml', language: 'yaml', content: buildDockerComposeFile() },
-      { name: 'bootstrap.sh', language: 'bash', content: buildDockerBootstrapScript() },
+      { name: 'cloud-init.yaml', language: 'yaml', content: buildCloudInitFile(bundleOptions) },
+      { name: '.env', language: 'env', content: buildDockerEnvFile(bundleOptions) },
+      { name: 'docker-compose.yml', language: 'yaml', content: buildDockerComposeFile(bundleOptions) },
+      { name: 'bootstrap.sh', language: 'bash', content: buildDockerBootstrapScript(bundleOptions) },
+      ...buildExposureFiles(bundleOptions),
     ],
   }
 }
+
+function buildSshInvocation(config: OpenClawSshConfig, remoteCommand: string): string {
+  return ['ssh', ...buildSshArgs(config), buildSshTarget(config), remoteCommand]
+    .map(shellEscape)
+    .join(' ')
+}
+
+function buildScpInvocation(config: OpenClawSshConfig, filePaths: string[]): string {
+  const destination = `${buildSshTarget(config)}:${config.targetDir || '/opt/openclaw'}/`
+  return ['scp', ...buildSshArgs(config, true), ...filePaths, destination]
+    .map(shellEscape)
+    .join(' ')
+}
+
+export async function verifyOpenClawDeployment(input?: {
+  endpoint?: string | null
+  credentialId?: string | null
+  token?: string | null
+  model?: string | null
+  timeoutMs?: number
+}): Promise<OpenClawHealthResult> {
+  return probeOpenClawHealth({
+    endpoint: input?.endpoint || null,
+    credentialId: input?.credentialId || null,
+    token: input?.token || null,
+    model: input?.model || null,
+    timeoutMs: input?.timeoutMs,
+  })
+}
+
+export async function deployOpenClawBundleOverSsh(input?: {
+  template?: OpenClawRemoteDeployTemplate
+  target?: string | null
+  token?: string | null
+  scheme?: 'http' | 'https'
+  port?: number
+  provider?: OpenClawRemoteDeployProvider
+  useCase?: OpenClawUseCaseTemplate
+  exposure?: OpenClawExposurePreset
+  ssh?: Partial<OpenClawSshConfig> | null
+}): Promise<OpenClawRemoteCommandResult> {
+  const sshConfig = sanitizeSshConfig(input?.ssh)
+  if (!sshConfig) throw new Error('SSH host is required for remote deploy.')
+
+  const bundle = buildOpenClawDeployBundle({
+    template: input?.template,
+    target: input?.target,
+    token: input?.token,
+    scheme: input?.scheme,
+    port: input?.port,
+    provider: input?.provider,
+    useCase: input?.useCase,
+    exposure: input?.exposure,
+  })
+  const materialized = await materializeBundleFiles(bundle)
+  const remoteDir = sshConfig.targetDir || '/opt/openclaw'
+  const mkdirCommand = buildSshInvocation(sshConfig, `mkdir -p ${shellEscape(remoteDir)}`)
+  const scpCommand = buildScpInvocation(sshConfig, materialized.filePaths)
+  const bootstrapCommand = buildSshInvocation(
+    sshConfig,
+    `cd ${shellEscape(remoteDir)} && chmod +x bootstrap.sh && OPENCLAW_APP_DIR=${shellEscape(remoteDir)} bash ./bootstrap.sh`,
+  )
+  const command = `${mkdirCommand} && ${scpCommand} && ${bootstrapCommand}`
+  const result = await startRemoteCommand({
+    action: 'ssh-deploy',
+    target: sshConfig.host,
+    command,
+    summary: `Deploying OpenClaw to ${sshConfig.host} over SSH.`,
+  })
+  return {
+    ...result,
+    token: bundle.token,
+    bundle,
+  }
+}
+
+export const deployOpenClawOverSsh = deployOpenClawBundleOverSsh
+
+export async function runOpenClawRemoteLifecycleAction(input?: {
+  action: 'start' | 'stop' | 'restart' | 'upgrade' | 'backup' | 'restore' | 'rotate-token'
+  ssh?: Partial<OpenClawSshConfig> | null
+  image?: string | null
+  token?: string | null
+  backupPath?: string | null
+}): Promise<OpenClawRemoteCommandResult> {
+  const sshConfig = sanitizeSshConfig(input?.ssh)
+  if (!sshConfig) throw new Error('SSH host is required for remote lifecycle actions.')
+  const remoteDir = sshConfig.targetDir || '/opt/openclaw'
+  const image = normalizeText(input?.image) || 'openclaw:latest'
+  const action = input?.action || 'restart'
+  let remoteCommand = ''
+  let summary = ''
+  let rotatedToken: string | undefined
+  let backupPath: string | null = null
+
+  if (action === 'start') {
+    remoteCommand = `cd ${shellEscape(remoteDir)} && docker compose up -d`
+    summary = `Starting OpenClaw on ${sshConfig.host}.`
+  } else if (action === 'stop') {
+    remoteCommand = `cd ${shellEscape(remoteDir)} && docker compose down`
+    summary = `Stopping OpenClaw on ${sshConfig.host}.`
+  } else if (action === 'restart') {
+    remoteCommand = `cd ${shellEscape(remoteDir)} && docker compose restart`
+    summary = `Restarting OpenClaw on ${sshConfig.host}.`
+  } else if (action === 'upgrade') {
+    remoteCommand = `cd ${shellEscape(remoteDir)} && docker pull ${shellEscape(image)} && docker compose up -d`
+    summary = `Pulling ${image} and recreating the OpenClaw stack on ${sshConfig.host}.`
+  } else if (action === 'backup') {
+    backupPath = path.posix.join(remoteDir, 'backups', `openclaw-backup-${Date.now()}.tgz`)
+    remoteCommand = `cd ${shellEscape(remoteDir)} && mkdir -p backups && tar -czf ${shellEscape(backupPath)} .env docker-compose.yml .openclaw workspace && printf '%s\\n' ${shellEscape(backupPath)}`
+    summary = `Creating an OpenClaw backup on ${sshConfig.host}.`
+  } else if (action === 'restore') {
+    backupPath = normalizeText(input?.backupPath) || null
+    if (!backupPath) throw new Error('A remote backup path is required for restore.')
+    remoteCommand = `cd ${shellEscape(remoteDir)} && tar -xzf ${shellEscape(backupPath)} -C ${shellEscape(remoteDir)} && docker compose up -d`
+    summary = `Restoring OpenClaw from ${backupPath} on ${sshConfig.host}.`
+  } else {
+    rotatedToken = normalizeToken(input?.token) || generateOpenClawGatewayToken()
+    remoteCommand = `cd ${shellEscape(remoteDir)} && sed -i.bak -e ${shellEscape(`s/^OPENCLAW_GATEWAY_TOKEN=.*/OPENCLAW_GATEWAY_TOKEN=${rotatedToken}/`)} .env && docker compose up -d && printf '%s\\n' ${shellEscape(rotatedToken)}`
+    summary = `Rotating the OpenClaw gateway token on ${sshConfig.host}.`
+  }
+
+  const command = buildSshInvocation(sshConfig, remoteCommand)
+  const result = await startRemoteCommand({
+    action,
+    target: sshConfig.host,
+    command,
+    summary,
+    backupPath,
+  })
+  return {
+    ...result,
+    token: rotatedToken,
+  }
+}
+
+export const runOpenClawRemoteLifecycle = runOpenClawRemoteLifecycleAction