@swarmclawai/swarmclaw 0.8.8 → 0.9.0

package/Dockerfile.sandbox-browser

@@ -0,0 +1,29 @@
+FROM debian:bookworm-slim@sha256:98f4b71de414932439ac6ac690d7060df1f27161073c5036a7553723881bffbe
+
+ENV DEBIAN_FRONTEND=noninteractive
+
+RUN apt-get update \
+  && apt-get install -y --no-install-recommends \
+    bash \
+    ca-certificates \
+    chromium \
+    curl \
+    fonts-liberation \
+    fonts-noto-color-emoji \
+    novnc \
+    socat \
+    websockify \
+    x11vnc \
+    xvfb \
+  && rm -rf /var/lib/apt/lists/*
+
+COPY scripts/sandbox-browser-entrypoint.sh /usr/local/bin/swarmclaw-sandbox-browser
+RUN chmod +x /usr/local/bin/swarmclaw-sandbox-browser
+
+RUN useradd --create-home --shell /bin/bash sandbox
+USER sandbox
+WORKDIR /home/sandbox
+
+EXPOSE 9222 5900 6080
+
+CMD ["swarmclaw-sandbox-browser"]

package/README.md

@@ -116,7 +116,7 @@ Skill source and runbook: [`swarmclaw/SKILL.md`](swarmclaw/SKILL.md).
 - **OpenAI Codex CLI** (optional, for `codex-cli` provider) — [Install](https://github.com/openai/codex)
 - **OpenCode CLI** (optional, for `opencode-cli` provider) — [Install](https://github.com/opencode-ai/opencode)
 - **Gemini CLI** (optional, for `delegate` backend `gemini`) — install and authenticate `gemini` on your host
-- **Deno** (required for `sandbox_exec`) — auto-installed by `npm run quickstart` / `npm run setup:easy` when missing
+- **Docker Desktop** (optional, recommended) — enables container sandboxes for shell, browser, and `sandbox_exec`; without Docker, SwarmClaw falls back to host execution
 
 ## Quick Start
 
@@ -129,16 +129,21 @@ npm i -g @swarmclawai/swarmclaw
 pnpm add -g @swarmclawai/swarmclaw
 yarn global add @swarmclawai/swarmclaw
 bun add -g @swarmclawai/swarmclaw
-swarmclaw
+swarmclaw server
 ```
 
+`swarmclaw` by itself opens the CLI. `swarmclaw server` launches the packaged standalone server on `http://localhost:3456`.
+Global install runs `postinstall`, which rebuilds `better-sqlite3` and prepares the sandbox browser image when Docker is available.
+If Docker is not installed yet, SwarmClaw keeps running and falls back to host execution for shell, browser, and `sandbox_exec`.
+No Deno install is required for the local `sandbox_exec` path.
+
 ### One-off run
 
 ```bash
-npx @swarmclawai/swarmclaw
-pnpm dlx @swarmclawai/swarmclaw
-yarn dlx @swarmclawai/swarmclaw
-bunx @swarmclawai/swarmclaw
+npx @swarmclawai/swarmclaw server
+pnpm dlx @swarmclawai/swarmclaw server
+yarn dlx @swarmclawai/swarmclaw server
+bunx @swarmclawai/swarmclaw server
 ```
 
 ### Install script
@@ -148,7 +153,9 @@ curl -fsSL https://raw.githubusercontent.com/swarmclawai/swarmclaw/main/install.
 ```
 
 The installer resolves the latest stable release tag and installs that version by default.
-To pin a version: `SWARMCLAW_VERSION=v0.8.7 curl ... | bash`
+It also builds the production bundle so `npm run start` is ready immediately after install.
+No Deno install is required; local sandbox execution is Docker-first with automatic host Node fallback.
+To pin a version: `SWARMCLAW_VERSION=v0.9.0 curl ... | bash`
 
 Or run locally from the repo (friendly for non-technical users):
 
@@ -160,11 +167,17 @@ npm run quickstart
 
 `npm run quickstart` will:
 - Check Node/npm versions
-- Install Deno if the sandbox runtime is missing
 - Install dependencies
+- Prepare the Docker sandbox/browser runtime when Docker is available
 - Prepare `.env.local` and `data/`
 - Start the app at `http://localhost:3456`
 
+For the packaged production server, use:
+
+```bash
+npm run quickstart:prod
+```
+
 If you prefer another package manager for local development:
 
 ```bash
@@ -173,7 +186,9 @@ yarn install && yarn dev
 bun install && bun run dev
 ```
 
-`postinstall` rebuilds `better-sqlite3` natively. If you install with `--ignore-scripts`, run `npm rebuild better-sqlite3` manually.
+`postinstall` rebuilds `better-sqlite3` natively and prepares the sandbox browser image when Docker is available.
+If Docker is missing, SwarmClaw falls back to host execution until Docker is installed.
+If you install with `--ignore-scripts`, run `npm rebuild better-sqlite3` manually and then `node ./scripts/ensure-sandbox-browser-image.mjs`.
 
 On first launch, SwarmClaw will:
 1. Generate an **access key** and display it in the terminal
@@ -374,7 +389,7 @@ Agents can use the following tools when enabled:
 | Image Generation | Generate images from prompts (`generate_image`) via OpenAI, Stability, Replicate, fal.ai, Together, Fireworks, BFL, or custom endpoints; saved to uploads |
 | Email | Send outbound email via SMTP (`email`) with `send`/`status` actions |
 | Calendar | Manage Google/Outlook events (`calendar`) with list/create/update/delete/status actions |
-| Sandbox | Run JS/TS in a Deno sandbox when custom code is necessary. If Deno is unavailable it fails closed with guidance; for simple API calls, prefer HTTP Request. |
+| Sandbox | Run JS/TS in a Docker-preferred Node.js sandbox when custom code is necessary. New and existing agents default to sandbox-enabled configs. If Docker is unavailable, SwarmClaw falls back to host execution; for simple API calls, prefer HTTP Request. |
 | MCP Servers | Connect to external Model Context Protocol servers. Tools from MCP servers are injected as first-class agent tools |
 
 ### Platform Tools
@@ -630,6 +645,7 @@ docker compose up -d
 ```
 
 Data is persisted in `data/` and `.env.local` via volume mounts. Updates: `git pull && docker compose up -d --build`.
+In Docker deployments, local shell, browser, and `sandbox_exec` execution fall back to host execution inside the app container unless you separately provide Docker access to that container.
 
 For prebuilt images (recommended for non-technical users after releases):
 
@@ -690,7 +706,7 @@ npm run dev:webpack
 ### First-Run Helpers
 
 ```bash
-npm run setup:easy      # setup only (installs Deno if missing; does not start server)
+npm run setup:easy      # setup only (prepares sandbox/browser runtime when Docker is available; does not start server)
 npm run quickstart      # setup + start dev server
 npm run quickstart:prod # setup + build + start production server
 npm run update:easy     # safe update helper for local installs
@@ -701,7 +717,7 @@ npm run update:easy     # safe update helper for local installs
 SwarmClaw uses tag-based releases (`vX.Y.Z`) as the stable channel.
 
 ```bash
-# example patch release (v0.8.7 style)
+# example release
 npm version patch
 git push origin main --follow-tags
 ```
@@ -711,14 +727,15 @@ On `v*` tags, GitHub Actions will:
 2. Create a GitHub Release
 3. Build and publish Docker images to `ghcr.io/swarmclawai/swarmclaw` (`:vX.Y.Z`, `:latest`, `:sha-*`)
 
-#### v0.8.7 Release Readiness Notes
+#### v0.9.0 Release Readiness Notes
 
-Before shipping `v0.8.7`, confirm the following user-facing changes are reflected in docs:
+Before shipping `v0.9.0`, confirm the following user-facing changes are reflected in docs:
 
-1. Install/update docs note that `v0.8.7` repairs the committed npm lockfile so `npm ci` succeeds again on clean GitHub Actions and operator installs.
-2. Site and README install/version strings are updated to `v0.8.7`, including install snippets, release notes index text, and sidebar/footer labels.
-3. Release notes make it explicit that this patch is a packaging/install integrity fix on top of the `v0.8.6` runtime changes, not a new behavior rollout.
-4. The release branch and `main` stay aligned so the shipped tag points at the same commit users see on the default branch.
+1. Install docs make it explicit that global npm installs use `swarmclaw server`, and that package-manager installs plus the curl installer prepare the sandbox/browser runtime automatically when Docker is available.
+2. Sandbox docs say local `sandbox_exec` no longer requires Deno, defaults to sandbox-enabled agent configs, and falls back to host Node when Docker is unavailable.
+3. Release docs mention the OpenClaw-style sandbox/runtime refresh, heartbeat deferral improvements, and the HMR-safe live chat route fix.
+4. Site and README install/version strings are updated to `v0.9.0`, including pinned install snippets, release notes index text, and sidebar/footer labels.
+5. The release tag, npm package version, and generated GitHub release install snippet all agree on the non-prefixed npm version (`0.9.0`) versus the git tag (`v0.9.0`).
 
 ## CLI
 

package/bin/update-cmd.js

@@ -36,10 +36,32 @@ function getLatestStableTag() {
   return tags.find((t) => RELEASE_TAG_RE.test(t)) || null
 }
 
+function rebuildStandaloneServer(
+  execImpl = execFileSync,
+  logger = { log, logError },
+) {
+  const serverCmdPath = path.join(PKG_ROOT, 'bin', 'server-cmd.js')
+  logger.log('Rebuilding the standalone server bundle...')
+  try {
+    execImpl(process.execPath, [serverCmdPath, '--build'], {
+      cwd: PKG_ROOT,
+      stdio: 'inherit',
+      timeout: 10 * 60_000,
+    })
+    logger.log('Standalone server bundle rebuilt.')
+    return 0
+  } catch (err) {
+    logger.logError(`Standalone rebuild failed: ${err.message}`)
+    logger.logError('Retry manually with: swarmclaw server --build')
+    return 1
+  }
+}
+
 function runRegistrySelfUpdate(
   packageManager = PACKAGE_MANAGER,
   execImpl = execFileSync,
   logger = { log, logError },
+  rebuildImpl = execFileSync,
 ) {
   const update = getGlobalUpdateSpec(packageManager, PACKAGE_NAME)
   logger.log(`No git checkout detected. Updating the global ${PACKAGE_NAME} install via ${packageManager}...`)
@@ -50,13 +72,17 @@ function runRegistrySelfUpdate(
       timeout: 120_000,
     })
     logger.log(`Global update complete via ${packageManager}.`)
-    logger.log('Restart the server to apply changes: swarmclaw server stop && swarmclaw server start')
-    return 0
   } catch (err) {
     logger.logError(`Registry update failed: ${err.message}`)
     logger.logError(`Retry manually with: ${update.display}`)
     return 1
   }
+
+  const rebuildExitCode = rebuildStandaloneServer(rebuildImpl, logger)
+  if (rebuildExitCode !== 0) return rebuildExitCode
+
+  logger.log('Restart the server to apply changes: swarmclaw server stop && swarmclaw server start')
+  return 0
 }
 
 function main() {

package/bin/update-cmd.test.js

@@ -3,36 +3,53 @@
 
 const test = require('node:test')
 const assert = require('node:assert/strict')
+const path = require('node:path')
 
 const { runRegistrySelfUpdate } = require('./update-cmd.js')
 
-test('runRegistrySelfUpdate executes the manager-specific global update command', () => {
+test('runRegistrySelfUpdate executes the manager-specific global update command and rebuilds the standalone server', () => {
   const messages = []
-  let captured = null
+  const captured = []
 
   const exitCode = runRegistrySelfUpdate(
     'pnpm',
     (command, args, options) => {
-      captured = { command, args, options }
+      captured.push({ command, args, options })
     },
     {
       log: (message) => messages.push(`log:${message}`),
       logError: (message) => messages.push(`err:${message}`),
     },
+    (command, args, options) => {
+      captured.push({ command, args, options })
+    },
   )
 
   assert.equal(exitCode, 0)
-  assert.deepEqual(captured, {
-    command: 'pnpm',
-    args: ['add', '-g', '@swarmclawai/swarmclaw@latest'],
-    options: {
-      cwd: process.cwd(),
-      stdio: 'inherit',
-      timeout: 120_000,
-    },
-  })
+  assert.deepEqual(captured, [
+    {
+      command: 'pnpm',
+      args: ['add', '-g', '@swarmclawai/swarmclaw@latest'],
+      options: {
+        cwd: process.cwd(),
+        stdio: 'inherit',
+        timeout: 120_000,
+      },
+    },
+    {
+      command: process.execPath,
+      args: [path.join(process.cwd(), 'bin', 'server-cmd.js'), '--build'],
+      options: {
+        cwd: process.cwd(),
+        stdio: 'inherit',
+        timeout: 600_000,
+      },
+    },
+  ])
   assert.match(messages.join('\n'), /updating the global @swarmclawai\/swarmclaw install via pnpm/i)
   assert.match(messages.join('\n'), /global update complete via pnpm/i)
+  assert.match(messages.join('\n'), /rebuilding the standalone server bundle/i)
+  assert.match(messages.join('\n'), /standalone server bundle rebuilt/i)
 })
 
 test('runRegistrySelfUpdate reports a manual retry command when the registry update fails', () => {
@@ -53,3 +70,23 @@ test('runRegistrySelfUpdate reports a manual retry command when the registry upd
   assert.match(messages.join('\n'), /registry update failed: spawn bun ENOENT/i)
   assert.match(messages.join('\n'), /retry manually with: bun add -g @swarmclawai\/swarmclaw@latest/i)
 })
+
+test('runRegistrySelfUpdate reports a manual rebuild command when the rebuild step fails', () => {
+  const messages = []
+
+  const exitCode = runRegistrySelfUpdate(
+    'npm',
+    () => {},
+    {
+      log: (message) => messages.push(`log:${message}`),
+      logError: (message) => messages.push(`err:${message}`),
+    },
+    () => {
+      throw new Error('build failed')
+    },
+  )
+
+  assert.equal(exitCode, 1)
+  assert.match(messages.join('\n'), /standalone rebuild failed: build failed/i)
+  assert.match(messages.join('\n'), /retry manually with: swarmclaw server --build/i)
+})

package/bundled-skills/google-workspace/SKILL.md

@@ -0,0 +1,94 @@
+---
+name: google-workspace
+description: Use Google Workspace CLI (`gws`) for Drive, Docs, Sheets, Gmail, Calendar, Chat, and related Workspace API tasks.
+homepage: https://github.com/googleworkspace/cli
+metadata:
+  openclaw:
+    requires:
+      bins: [gws]
+---
+
+# Google Workspace CLI
+
+Use `gws` when the task is about Google Workspace resources or Google Workspace API automation.
+
+Prefer `gws` over generic HTTP calls when possible because it already knows the Workspace API surface and returns structured JSON by default.
+
+## Rules
+
+1. Start with read/list/get commands before mutating Workspace state.
+2. Confirm IDs first: document IDs, spreadsheet IDs, file IDs, message IDs, calendar IDs, space IDs.
+3. Do not run interactive auth flows from an agent tool call. If auth is missing, report that `gws` needs to be configured in plugin settings or via a manual terminal login.
+4. Keep commands machine-readable. Prefer JSON output and parse it instead of scraping human text.
+5. For large list operations, limit the scope first, then page or filter.
+
+## Common Commands
+
+Check installation and health:
+
+```bash
+gws doctor
+```
+
+Inspect help for a resource or method:
+
+```bash
+gws help
+gws drive help
+gws drive files help
+```
+
+Google Docs:
+
+```bash
+gws docs get --document-id <DOC_ID>
+```
+
+Google Drive:
+
+```bash
+gws drive files list --params '{"pageSize":10}'
+gws drive files get --file-id <FILE_ID>
+```
+
+Google Sheets:
+
+```bash
+gws sheets spreadsheets get --spreadsheet-id <SPREADSHEET_ID>
+```
+
+Gmail:
+
+```bash
+gws gmail users messages list --user-id me --params '{"maxResults":10}'
+gws gmail users messages get --user-id me --message-id <MESSAGE_ID>
+```
+
+Google Calendar:
+
+```bash
+gws calendar events list --calendar-id primary --params '{"maxResults":10,"singleEvents":true}'
+```
+
+Google Chat:
+
+```bash
+gws chat spaces messages list --parent spaces/<SPACE_ID>
+```
+
+## Tool Usage In SwarmClaw
+
+When using the `google_workspace` tool:
+
+- Put the `gws` command after the binary into `args`, for example:
+  `{"args":["drive","files","list"],"params":{"pageSize":5}}`
+- Use `params` for `--params`
+- Use `jsonInput` for `--json`
+- Use `pageAll: true` when you intentionally want all pages
+- Use `dryRun: true` before risky mutations if you are unsure
+
+## Error Handling
+
+- If `gws` is missing: tell the user to install Google Workspace CLI.
+- If auth is missing or expired: tell the user to configure the plugin settings or authenticate `gws` manually.
+- If a command fails because an ID is missing: switch to a list/search command first and find the right ID.

package/next.config.ts

@@ -3,7 +3,6 @@ import { execSync } from "child_process";
 import { networkInterfaces } from "os";
 import path from "path";
 import { fileURLToPath } from "url";
-import { DIRECT_NAV_SEGMENTS } from "./view-route-paths";
 
 const PROJECT_ROOT = path.dirname(fileURLToPath(import.meta.url))
 
@@ -76,19 +75,6 @@ const nextConfig: NextConfig = {
     'qrcode',
   ],
   allowedDevOrigins: getAllowedDevOrigins(),
-  async rewrites() {
-    const views = DIRECT_NAV_SEGMENTS.join('|')
-    return [
-      {
-        source: `/:view(${views})`,
-        destination: '/',
-      },
-      {
-        source: `/:view(${views})/:id`,
-        destination: '/',
-      },
-    ]
-  },
 };
 
 export default nextConfig;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@swarmclawai/swarmclaw",
-  "version": "0.8.8",
+  "version": "0.9.0",
   "description": "Self-hosted AI agent orchestration dashboard — manage LLM providers, orchestrate agent swarms, schedule tasks, and bridge agents to chat platforms.",
   "license": "MIT",
   "publishConfig": {
@@ -29,9 +29,15 @@
   },
   "files": [
     "bin/",
+    "bundled-skills/",
     "src/",
     "public/",
+    "Dockerfile.sandbox-browser",
+    "scripts/easy-setup.mjs",
+    "scripts/easy-update.mjs",
+    "scripts/ensure-sandbox-browser-image.mjs",
     "scripts/postinstall.mjs",
+    "scripts/sandbox-browser-entrypoint.sh",
     "next.config.ts",
     "tsconfig.json",
     "postcss.config.mjs",
@@ -42,15 +48,16 @@
     "quickstart": "node ./scripts/easy-setup.mjs --start",
     "quickstart:prod": "node ./scripts/easy-setup.mjs --prod",
     "update:easy": "node ./scripts/easy-update.mjs",
-    "dev": "next dev --webpack --hostname 0.0.0.0 -p 3456",
+    "dev": "next dev --turbopack --hostname 0.0.0.0 -p 3456",
     "dev:webpack": "next dev --webpack --hostname 0.0.0.0 -p 3456",
-    "dev:clean": "rm -rf .next && next dev --hostname 0.0.0.0 -p 3456",
+    "dev:clean": "rm -rf .next && next dev --turbopack --hostname 0.0.0.0 -p 3456",
     "build": "next build",
     "build:ci": "NEXT_DISABLE_ESLINT=1 next build",
     "start": "node .next/standalone/server.js",
     "start:standalone": "node .next/standalone/server.js",
     "smoke:browser": "node ./scripts/browser-route-smoke.mjs",
     "smoke:browser:workbench": "node ./scripts/browser-workbench-smoke.mjs",
+    "sandbox:build:browser": "docker build -f Dockerfile.sandbox-browser -t swarmclaw-sandbox-browser:bookworm-slim .",
     "benchmark:autonomy": "node ./scripts/benchmark-autonomy-harness.mjs",
     "benchmark:agent-regression": "node --import tsx ./scripts/run-agent-regression-suite.ts",
     "lint": "eslint",
@@ -59,15 +66,15 @@
     "lint:baseline:update": "node ./scripts/lint-baseline.mjs update",
     "cli": "node ./bin/swarmclaw.js",
     "test:cli": "node --test src/cli/*.test.js bin/*.test.js",
-    "test:openclaw": "tsx --test src/lib/openclaw-agent-id.test.ts src/lib/openclaw-endpoint.test.ts src/lib/server/agent-runtime-config.test.ts src/lib/server/build-llm.test.ts src/lib/server/connectors/connector-routing.test.ts src/lib/server/connectors/openclaw.test.ts src/lib/server/gateway/protocol.test.ts src/lib/server/llm-response-cache.test.ts src/lib/server/mcp-conformance.test.ts src/lib/server/openclaw-agent-resolver.test.ts src/lib/server/openclaw-deploy.test.ts src/lib/server/openclaw-skills-normalize.test.ts src/lib/server/session-tools/openclaw-nodes.test.ts src/lib/server/task-quality-gate.test.ts src/lib/server/task-validation.test.ts src/lib/server/tool-capability-policy.test.ts",
+    "test:openclaw": "tsx --test src/lib/openclaw/openclaw-agent-id.test.ts src/lib/openclaw/openclaw-endpoint.test.ts src/lib/server/agents/agent-runtime-config.test.ts src/lib/server/build-llm.test.ts src/lib/server/connectors/connector-routing.test.ts src/lib/server/connectors/openclaw.test.ts src/lib/server/gateway/protocol.test.ts src/lib/server/llm-response-cache.test.ts src/lib/server/mcp-conformance.test.ts src/lib/server/openclaw/agent-resolver.test.ts src/lib/server/openclaw/deploy.test.ts src/lib/server/openclaw/skills-normalize.test.ts src/lib/server/session-tools/openclaw-nodes.test.ts src/lib/server/tasks/task-quality-gate.test.ts src/lib/server/tasks/task-validation.test.ts src/lib/server/tool-capability-policy.test.ts",
     "test:mcp:conformance": "node --import tsx ./scripts/mcp-conformance-check.ts",
     "postinstall": "node ./scripts/postinstall.mjs"
   },
   "dependencies": {
     "@huggingface/transformers": "^3.8.1",
     "@langchain/anthropic": "^1.3.18",
-    "@langchain/core": "^1.1.26",
-    "@langchain/langgraph": "^1.1.5",
+    "@langchain/core": "^1.1.31",
+    "@langchain/langgraph": "^1.2.2",
     "@langchain/openai": "^1.2.8",
     "@multiavatar/multiavatar": "^1.0.7",
     "@playwright/mcp": "^0.0.68",
@@ -88,6 +95,7 @@
     "grammy": "^1.40.0",
     "highlight.js": "^11.11.1",
     "imapflow": "^1.2.11",
+    "langchain": "^1.2.30",
     "lucide-react": "^0.574.0",
     "mailparser": "^3.9.3",
     "next": "16.1.6",
@@ -133,6 +141,8 @@
   "optionalDependencies": {
     "botbuilder": "^4.23.3",
     "googleapis": "^171.4.0",
-    "matrix-bot-sdk": "^0.8.0"
+    "matrix-bot-sdk": "^0.8.0",
+    "opusscript": "0.0.8",
+    "utf-8-validate": "5.0.10"
   }
 }

package/scripts/easy-setup.mjs

@@ -0,0 +1,145 @@
+#!/usr/bin/env node
+
+import fs from 'node:fs'
+import path from 'node:path'
+import { spawnSync } from 'node:child_process'
+
+const args = new Set(process.argv.slice(2))
+const startAfterSetup = args.has('--start') || args.has('--prod')
+const productionMode = args.has('--prod')
+const skipInstall = args.has('--skip-install')
+const cwd = process.cwd()
+
+function log(message) {
+  process.stdout.write(`[setup] ${message}\n`)
+}
+
+function fail(message, code = 1) {
+  process.stderr.write(`[setup] ERROR: ${message}\n`)
+  process.exit(code)
+}
+
+function run(command, commandArgs, options = {}) {
+  const printable = `${command} ${commandArgs.join(' ')}`.trim()
+  log(`$ ${printable}`)
+  const result = spawnSync(command, commandArgs, {
+    cwd,
+    stdio: 'inherit',
+    ...options,
+  })
+  if (result.error) fail(result.error.message)
+  if ((result.status ?? 1) !== 0) {
+    fail(`Command failed: ${printable}`, result.status ?? 1)
+  }
+}
+
+function runOptional(command, commandArgs, options = {}) {
+  const printable = `${command} ${commandArgs.join(' ')}`.trim()
+  log(`$ ${printable}`)
+  const result = spawnSync(command, commandArgs, {
+    cwd,
+    stdio: 'inherit',
+    ...options,
+  })
+  if (result.error || (result.status ?? 1) !== 0) {
+    log(`Optional step failed: ${printable}`)
+    return false
+  }
+  return true
+}
+
+function ensureNodeVersion() {
+  const version = process.versions.node
+  const [majorRaw, minorRaw] = version.split('.')
+  const major = Number.parseInt(majorRaw || '0', 10)
+  const minor = Number.parseInt(minorRaw || '0', 10)
+  if (major < 22 || (major === 22 && minor < 6)) {
+    fail(`Detected Node ${version}. SwarmClaw requires Node 22.6 or newer.`)
+  }
+  log(`Node ${version} detected.`)
+}
+
+function ensureNpm() {
+  const result = spawnSync('npm', ['--version'], { cwd, encoding: 'utf8' })
+  if (result.error || (result.status ?? 1) !== 0) {
+    fail('npm was not found. Install npm and rerun this setup command.')
+  }
+  log(`npm ${String(result.stdout || '').trim()} detected.`)
+}
+
+function commandExists(name) {
+  const lookup = process.platform === 'win32' ? 'where' : 'which'
+  const result = spawnSync(lookup, [name], { cwd, encoding: 'utf8' })
+  return !result.error && (result.status ?? 1) === 0
+}
+
+function ensureProjectRoot() {
+  const pkgPath = path.join(cwd, 'package.json')
+  if (!fs.existsSync(pkgPath)) {
+    fail(`package.json was not found in ${cwd}. Run this command from the SwarmClaw project root.`)
+  }
+}
+
+function ensureEnvFile() {
+  const envPath = path.join(cwd, '.env.local')
+  if (!fs.existsSync(envPath)) {
+    fs.writeFileSync(
+      envPath,
+      '# SwarmClaw local environment variables\n# ACCESS_KEY and CREDENTIAL_SECRET are auto-generated on first app run.\n',
+      'utf8',
+    )
+    log('Created .env.local.')
+  } else {
+    log('.env.local already exists.')
+  }
+}
+
+function ensureDataDir() {
+  const dataDir = path.join(cwd, 'data')
+  fs.mkdirSync(dataDir, { recursive: true })
+  log(`Data directory ready at ${dataDir}.`)
+}
+
+function printNextSteps() {
+  process.stdout.write('\n')
+  log('Setup complete.')
+  process.stdout.write('\n')
+  process.stdout.write('Next steps:\n')
+  process.stdout.write('1. Run `npm run dev`.\n')
+  process.stdout.write('2. Open http://localhost:3456 in your browser.\n')
+  process.stdout.write('3. Copy the access key printed in the terminal and finish the setup wizard.\n')
+  process.stdout.write('   Or run `npx swarmclaw setup init` for interactive CLI setup.\n')
+  process.stdout.write('4. For updates later, run `npm run update:easy`.\n')
+}
+
+function main() {
+  ensureProjectRoot()
+  ensureNodeVersion()
+  ensureNpm()
+  ensureDataDir()
+  ensureEnvFile()
+
+  if (!skipInstall) {
+    run('npm', ['install'])
+  } else {
+    log('Skipping dependency install (--skip-install).')
+  }
+
+  runOptional('node', ['./scripts/ensure-sandbox-browser-image.mjs'])
+  if (!commandExists('docker')) {
+    log('Docker not detected. SwarmClaw will fall back to host execution until Docker Desktop is installed.')
+  }
+
+  if (productionMode) {
+    run('npm', ['run', 'build'])
+  }
+
+  if (startAfterSetup) {
+    run('npm', ['run', productionMode ? 'start' : 'dev'])
+    return
+  }
+
+  printNextSteps()
+}
+
+main()