@better-openclaw/core 1.0.6 → 1.0.8

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@better-openclaw/core",
-  "version": "1.0.6",
+  "version": "1.0.8",
   "private": false,
   "description": "Core logic for better-openclaw: schemas, service registry, resolver, composer, validators and more",
   "packageManager": "pnpm@9.15.4",
@@ -9,17 +9,17 @@
   "types": "dist/index.d.ts",
   "type": "module",
   "exports": {
-        ".": {
-            "types": "./dist/index.d.ts",
-            "import": "./dist/index.mjs",
-            "default": "./dist/index.mjs"
-        },
-        "./*": {
-            "types": "./dist/*.d.ts",
-            "import": "./dist/*.mjs",
-            "default": "./dist/*.mjs"
-        }
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "default": "./dist/index.mjs"
     },
+    "./*": {
+      "types": "./dist/*.d.ts",
+      "import": "./dist/*.mjs",
+      "default": "./dist/*.mjs"
+    }
+  },
   "scripts": {
     "build": "tsdown",
     "build:tsc": "tsc",
@@ -38,9 +38,10 @@
     "zod": "^4.3.6"
   },
   "devDependencies": {
+    "@biomejs/biome": "^2.0.0",
     "@types/node": "^25.2.2",
-    "tsdown": "^0.19.0",
+    "tsdown": "^0.20.3",
     "typescript": "^5.9.3",
     "vitest": "^4.0.18"
   }
-}
+}

package/src/schema.ts

@@ -20,6 +20,8 @@ export const ServiceCategorySchema = z.enum([
 	"ai-platform",
 	"dev-tools",
 	"knowledge",
+	"desktop",
+	"streaming",
 ]);
 
 export const MaturitySchema = z.enum(["stable", "beta", "experimental"]);
@@ -41,7 +43,7 @@ export const RestartPolicySchema = z.enum(["unless-stopped", "always", "on-failu
 
 export const ProxyTypeSchema = z.enum(["none", "caddy", "traefik"]);
 
-export const DeploymentTargetSchema = z.enum(["local", "vps", "homelab"]);
+export const DeploymentTargetSchema = z.enum(["local", "vps", "homelab", "clawexa"]);
 
 export const OutputFormatSchema = z.enum(["directory", "tar", "zip"]);
 
@@ -155,6 +157,7 @@ export const ServiceDefinitionSchema = z.object({
 	recommends: z.array(z.string()).default([]),
 	conflictsWith: z.array(z.string()).default([]),
 	mandatory: z.boolean().default(false).optional(),
+	removalWarning: z.string().optional(),
 
 	// Platform Constraints
 	platforms: z.array(PlatformSchema).optional(),

package/src/services/definitions/comfyui.ts

@@ -0,0 +1,90 @@
+import type { ServiceDefinition } from "../../types.js";
+
+export const comfyuiDefinition: ServiceDefinition = {
+	id: "comfyui",
+	name: "ComfyUI",
+	description:
+		"Node-based visual workflow editor for Stable Diffusion and other generative AI models. Design complex image/video generation pipelines with a drag-and-drop graph UI and a powerful REST API.",
+	category: "ai",
+	icon: "🎨",
+
+	image: "ghcr.io/ai-dock/comfyui",
+	imageTag: "latest",
+	ports: [
+		{
+			host: 8188,
+			container: 8188,
+			description: "ComfyUI Web UI & API",
+			exposed: true,
+		},
+	],
+	volumes: [
+		{
+			name: "comfyui-models",
+			containerPath: "/opt/ComfyUI/models",
+			description: "Model checkpoint, LoRA, VAE, and ControlNet files",
+		},
+		{
+			name: "comfyui-output",
+			containerPath: "/opt/ComfyUI/output",
+			description: "Generated images and output files",
+		},
+		{
+			name: "comfyui-custom-nodes",
+			containerPath: "/opt/ComfyUI/custom_nodes",
+			description: "Community custom node extensions",
+		},
+	],
+	environment: [],
+	healthcheck: {
+		test: "curl -f http://localhost:8188/system_stats || exit 1",
+		interval: "30s",
+		timeout: "10s",
+		retries: 3,
+		startPeriod: "60s",
+	},
+	dependsOn: [],
+	restartPolicy: "unless-stopped",
+	networks: ["openclaw-network"],
+
+	skills: [{ skillId: "comfyui-generate", autoInstall: true }],
+	openclawEnvVars: [
+		{
+			key: "COMFYUI_HOST",
+			defaultValue: "comfyui",
+			secret: false,
+			description: "ComfyUI hostname for OpenClaw",
+			required: true,
+		},
+		{
+			key: "COMFYUI_PORT",
+			defaultValue: "8188",
+			secret: false,
+			description: "ComfyUI API port for OpenClaw",
+			required: true,
+		},
+	],
+
+	docsUrl: "https://github.com/comfyanonymous/ComfyUI",
+	selfHostedDocsUrl: "https://github.com/comfyanonymous/ComfyUI",
+	tags: [
+		"image-generation",
+		"ai-art",
+		"stable-diffusion",
+		"workflow",
+		"node-editor",
+		"text-to-image",
+		"comfyui",
+	],
+	maturity: "experimental",
+
+	requires: [],
+	recommends: ["ollama"],
+	conflictsWith: [],
+
+	removalWarning:
+		"⚠️ GPU INFRASTRUCTURE REQUIRED: ComfyUI requires an NVIDIA GPU with CUDA support and the NVIDIA Container Toolkit (nvidia-docker2) installed on the host. Without GPU acceleration, image generation will be extremely slow (minutes per image). Ensure your deployment target has adequate GPU resources (minimum 4 GB VRAM, 8 GB+ recommended) before adding this service.",
+
+	minMemoryMB: 4096,
+	gpuRequired: true,
+};

package/src/services/definitions/convex-dashboard.ts

@@ -0,0 +1,48 @@
+import type { ServiceDefinition } from "../../types.js";
+
+export const convexDashboardDefinition: ServiceDefinition = {
+	id: "convex-dashboard",
+	name: "Convex Dashboard",
+	description:
+		"Web dashboard for the self-hosted Convex backend. Browse data, run functions, view logs, and manage your deployment.",
+	category: "dev-tools",
+	icon: "📊",
+
+	image: "ghcr.io/get-convex/convex-dashboard",
+	imageTag: "latest",
+	ports: [
+		{
+			host: 6791,
+			container: 6791,
+			description: "Convex Dashboard Web UI",
+			exposed: true,
+		},
+	],
+	volumes: [],
+	environment: [
+		{
+			key: "NEXT_PUBLIC_DEPLOYMENT_URL",
+			defaultValue: "http://convex:3210",
+			secret: false,
+			description: "URL of the Convex backend (use Docker service name)",
+			required: true,
+		},
+	],
+	dependsOn: ["convex"],
+	restartPolicy: "unless-stopped",
+	networks: ["openclaw-network"],
+
+	skills: [],
+	openclawEnvVars: [],
+
+	docsUrl: "https://github.com/get-convex/convex-backend",
+	tags: ["convex", "dashboard", "admin", "database-ui"],
+	maturity: "stable",
+
+	requires: ["convex"],
+	recommends: [],
+	conflictsWith: [],
+
+	minMemoryMB: 128,
+	gpuRequired: false,
+};

package/src/services/definitions/convex.ts

@@ -0,0 +1,123 @@
+import type { ServiceDefinition } from "../../types.js";
+
+export const convexDefinition: ServiceDefinition = {
+	id: "convex",
+	name: "Convex",
+	description:
+		"Self-hosted Convex reactive backend. Real-time database, server functions, and file storage in a single service. Required by Mission Control.",
+	category: "database",
+	icon: "⚡",
+
+	image: "ghcr.io/get-convex/convex-backend",
+	imageTag: "latest",
+	ports: [
+		{
+			host: 3210,
+			container: 3210,
+			description: "Convex API (client connections & CLI)",
+			exposed: true,
+		},
+		{
+			host: 3211,
+			container: 3211,
+			description: "Convex HTTP actions / site proxy",
+			exposed: true,
+		},
+	],
+	volumes: [
+		{
+			name: "convex-data",
+			containerPath: "/convex/data",
+			description: "Convex data directory (SQLite by default)",
+		},
+	],
+	environment: [
+		{
+			key: "CONVEX_CLOUD_ORIGIN",
+			defaultValue: "http://127.0.0.1:3210",
+			secret: false,
+			description: "Public URL for the Convex API endpoint",
+			required: true,
+		},
+		{
+			key: "CONVEX_SITE_ORIGIN",
+			defaultValue: "http://127.0.0.1:3211",
+			secret: false,
+			description: "Public URL for Convex HTTP actions",
+			required: true,
+		},
+		{
+			key: "INSTANCE_NAME",
+			defaultValue: "openclaw-convex",
+			secret: false,
+			description: "Instance name for this Convex deployment",
+			required: false,
+		},
+		{
+			key: "INSTANCE_SECRET",
+			defaultValue: "",
+			secret: true,
+			description: "Instance secret (generate a random value for production)",
+			required: false,
+		},
+		{
+			key: "DATABASE_URL",
+			defaultValue: "",
+			secret: true,
+			description:
+				"Optional Postgres connection string for production (leave empty to use SQLite)",
+			required: false,
+		},
+		{
+			key: "RUST_LOG",
+			defaultValue: "info",
+			secret: false,
+			description: "Log level for the Convex backend (debug, info, warn, error)",
+			required: false,
+		},
+		{
+			key: "DISABLE_BEACON",
+			defaultValue: "",
+			secret: false,
+			description: "Set to any value to disable anonymous usage telemetry",
+			required: false,
+		},
+		{
+			key: "CONVEX_SELF_HOSTED_ADMIN_KEY",
+			defaultValue: "",
+			secret: true,
+			description:
+				"Admin key for CLI access. Generate with: docker compose exec convex ./generate_admin_key.sh",
+			required: false,
+		},
+	],
+	healthcheck: {
+		test: "curl -f http://localhost:3210/version",
+		interval: "5s",
+		timeout: "5s",
+		retries: 5,
+		startPeriod: "10s",
+	},
+	dependsOn: [],
+	restartPolicy: "unless-stopped",
+	networks: ["openclaw-network"],
+
+	skills: [],
+	openclawEnvVars: [],
+
+	docsUrl: "https://github.com/get-convex/convex-backend",
+	selfHostedDocsUrl:
+		"https://github.com/get-convex/convex-backend/blob/main/self-hosted/README.md",
+	tags: ["convex", "database", "reactive", "real-time", "backend", "self-hosted"],
+	maturity: "stable",
+
+	requires: [],
+	recommends: ["convex-dashboard"],
+	conflictsWith: [],
+	mandatory: true,
+	removalWarning:
+		"Convex is the backend for Mission Control. Without it, Mission Control will not be able to store or retrieve any data and will be completely non-functional.",
+
+	minMemoryMB: 256,
+	gpuRequired: false,
+};

package/src/services/definitions/desktop-environment.ts

@@ -0,0 +1,163 @@
+import type { ServiceDefinition } from "../../types.js";
+
+export const desktopEnvironmentDefinition: ServiceDefinition = {
+	id: "desktop-environment",
+	name: "Desktop Environment",
+	description:
+		"Isolated KasmVNC-based Linux desktop that gives AI agents full computer-use capabilities — screen vision, mouse/keyboard control, file management, and application launching (VS Code, Chrome, Firefox). OBS Studio is pre-installed for optional recording or live-streaming.",
+	category: "desktop",
+	icon: "🖥️",
+
+	image: "kasmweb/core-ubuntu-jammy",
+	imageTag: "1.16.0",
+	ports: [
+		{
+			host: 6901,
+			container: 6901,
+			description: "KasmVNC web interface (browser-based desktop access)",
+			exposed: true,
+		},
+		{
+			host: 5900,
+			container: 5900,
+			description: "VNC protocol port (native VNC clients)",
+			exposed: false,
+		},
+		{
+			host: 4455,
+			container: 4455,
+			description: "OBS WebSocket control port (when OBS is running)",
+			exposed: false,
+		},
+	],
+	volumes: [
+		{
+			name: "desktop-config",
+			containerPath: "/home/kasm-user",
+			description: "Desktop user home with config persistence",
+		},
+		{
+			name: "desktop-workspace",
+			containerPath: "/home/kasm-user/workspace",
+			description: "Shared workspace directory for files and projects",
+		},
+	],
+	environment: [
+		{
+			key: "VNC_PW",
+			defaultValue: "changeme",
+			secret: true,
+			description: "Password for VNC / KasmVNC web access",
+			required: true,
+		},
+		{
+			key: "VNC_RESOLUTION",
+			defaultValue: "1920x1080",
+			secret: false,
+			description: "Desktop screen resolution (WidthxHeight)",
+			required: false,
+		},
+		{
+			key: "SSL_VNC_ONLY",
+			defaultValue: "false",
+			secret: false,
+			description:
+				"When false, allows HTTP/WS connections without SSL (useful for local/Docker networking)",
+			required: false,
+		},
+		{
+			key: "OBS_WS_PORT",
+			defaultValue: "4455",
+			secret: false,
+			description: "OBS WebSocket port (used when OBS is launched manually)",
+			required: false,
+		},
+		{
+			key: "OBS_PASSWORD",
+			defaultValue: "changeme",
+			secret: true,
+			description: "OBS WebSocket password (used when OBS is launched manually)",
+			required: false,
+		},
+	],
+	healthcheck: {
+		test: "curl -sfk https://localhost:6901/ > /dev/null || curl -sf http://localhost:6901/ > /dev/null || exit 1",
+		interval: "10s",
+		timeout: "10s",
+		retries: 6,
+		startPeriod: "60s",
+	},
+	dependsOn: [],
+	restartPolicy: "unless-stopped",
+	networks: ["openclaw-network"],
+
+	deploy: {
+		resources: {
+			limits: { cpus: "4.0", memory: "8G" },
+			reservations: { cpus: "2.0", memory: "4G" },
+		},
+	},
+
+	skills: [{ skillId: "desktop-use", autoInstall: true }],
+	openclawEnvVars: [
+		{
+			key: "DESKTOP_HOST",
+			defaultValue: "desktop-environment",
+			secret: false,
+			description: "Hostname of the desktop-environment container",
+			required: true,
+		},
+		{
+			key: "DESKTOP_VNC_PORT",
+			defaultValue: "6901",
+			secret: false,
+			description: "KasmVNC web port",
+			required: true,
+		},
+		{
+			key: "DESKTOP_VNC_PASSWORD",
+			defaultValue: "${VNC_PW}",
+			secret: true,
+			description: "VNC password (references service password)",
+			required: true,
+		},
+	],
+
+	docsUrl: "https://www.kasmweb.com/docs/latest/index.html",
+	tags: [
+		"computer-use",
+		"vnc",
+		"desktop",
+		"screen-capture",
+		"automation",
+		"obs",
+		"kasm",
+	],
+	maturity: "experimental",
+
+	requires: [],
+	recommends: ["stream-gateway"],
+	conflictsWith: [],
+
+	removalWarning:
+		"⚠️ HEAVY RESOURCE USAGE: The desktop environment requires at least 4 GB RAM (8 GB recommended) and 2+ CPU cores. It runs a full Linux desktop with XFCE inside KasmVNC. OBS Studio is pre-installed but NOT auto-started — launch it manually or via agent tools when needed. Ensure your deployment target can handle these resources alongside other services.",
+	minMemoryMB: 4096,
+	gpuRequired: false,
+
+	nativeSupported: true,
+	nativeRecipes: [
+		{
+			platform: "linux",
+			installSteps: [
+				"command -v Xvfb >/dev/null 2>&1 || (command -v apt-get >/dev/null 2>&1 && sudo apt-get update -qq && sudo apt-get install -y -qq xvfb xfce4 xfce4-terminal tigervnc-standalone-server scrot xdotool xclip)",
+				"command -v obs >/dev/null 2>&1 || (sudo add-apt-repository -y ppa:obsproject/obs-studio && sudo apt-get update -qq && sudo apt-get install -y -qq obs-studio)",
+			],
+			startCommand:
+				"vncserver :1 -geometry 1920x1080 -depth 24 -localhost no 2>/dev/null || Xvfb :1 -screen 0 1920x1080x24 &",
+			stopCommand: "vncserver -kill :1 2>/dev/null; killall Xvfb 2>/dev/null",
+			configPath: "/etc/vnc/xstartup",
+			configTemplate:
+				"#!/bin/sh\n# Generated for OpenClaw bare-metal desktop\nexport DISPLAY=:1\nstartxfce4 &\n",
+		},
+	],
+};

package/src/services/definitions/index.ts

@@ -6,8 +6,12 @@ export { caddyDefinition } from "./caddy.js";
 export { chromadbDefinition } from "./chromadb.js";
 export { claudeCodeDefinition } from "./claude-code.js";
 export { codeServerDefinition } from "./code-server.js";
+export { comfyuiDefinition } from "./comfyui.js";
+export { convexDefinition } from "./convex.js";
+export { convexDashboardDefinition } from "./convex-dashboard.js";
 export { codexDefinition } from "./codex.js";
 export { coolifyDefinition } from "./coolify.js";
+export { desktopEnvironmentDefinition } from "./desktop-environment.js";
 export { difyDefinition } from "./dify.js";
 export { docsgptDefinition } from "./docsgpt.js";
 export { dokployDefinition } from "./dokploy.js";
@@ -30,6 +34,7 @@ export { matomoDefinition } from "./matomo.js";
 export { matrixSynapseDefinition } from "./matrix-synapse.js";
 export { mattermostDefinition } from "./mattermost.js";
 export { meilisearchDefinition } from "./meilisearch.js";
+export { missionControlDefinition } from "./mission-control.js";
 export { minioDefinition } from "./minio.js";
 export { mixpostDefinition } from "./mixpost.js";
 export { motionCanvasDefinition } from "./motion-canvas.js";
@@ -54,10 +59,12 @@ export { rocketchatDefinition } from "./rocketchat.js";
 export { searxngDefinition } from "./searxng.js";
 export { stableDiffusionDefinition } from "./stable-diffusion.js";
 export { steelBrowserDefinition } from "./steel-browser.js";
+export { streamGatewayDefinition } from "./stream-gateway.js";
 export { tailscaleDefinition } from "./tailscale.js";
 export { temporalDefinition } from "./temporal.js";
 export { traefikDefinition } from "./traefik.js";
 export { umamiDefinition } from "./umami.js";
+export { usesendDefinition } from "./usesend.js";
 export { uptimeKumaDefinition } from "./uptime-kuma.js";
 export { valkeyDefinition } from "./valkey.js";
 export { watchtowerDefinition } from "./watchtower.js";
@@ -73,8 +80,12 @@ import { caddyDefinition } from "./caddy.js";
 import { chromadbDefinition } from "./chromadb.js";
 import { claudeCodeDefinition } from "./claude-code.js";
 import { codeServerDefinition } from "./code-server.js";
+import { comfyuiDefinition } from "./comfyui.js";
+import { convexDefinition } from "./convex.js";
+import { convexDashboardDefinition } from "./convex-dashboard.js";
 import { codexDefinition } from "./codex.js";
 import { coolifyDefinition } from "./coolify.js";
+import { desktopEnvironmentDefinition } from "./desktop-environment.js";
 import { difyDefinition } from "./dify.js";
 import { docsgptDefinition } from "./docsgpt.js";
 import { dokployDefinition } from "./dokploy.js";
@@ -97,6 +108,7 @@ import { matomoDefinition } from "./matomo.js";
 import { matrixSynapseDefinition } from "./matrix-synapse.js";
 import { mattermostDefinition } from "./mattermost.js";
 import { meilisearchDefinition } from "./meilisearch.js";
+import { missionControlDefinition } from "./mission-control.js";
 import { minioDefinition } from "./minio.js";
 import { mixpostDefinition } from "./mixpost.js";
 import { motionCanvasDefinition } from "./motion-canvas.js";
@@ -121,10 +133,12 @@ import { rocketchatDefinition } from "./rocketchat.js";
 import { searxngDefinition } from "./searxng.js";
 import { stableDiffusionDefinition } from "./stable-diffusion.js";
 import { steelBrowserDefinition } from "./steel-browser.js";
+import { streamGatewayDefinition } from "./stream-gateway.js";
 import { tailscaleDefinition } from "./tailscale.js";
 import { temporalDefinition } from "./temporal.js";
 import { traefikDefinition } from "./traefik.js";
 import { umamiDefinition } from "./umami.js";
+import { usesendDefinition } from "./usesend.js";
 import { uptimeKumaDefinition } from "./uptime-kuma.js";
 import { valkeyDefinition } from "./valkey.js";
 import { watchtowerDefinition } from "./watchtower.js";
@@ -165,6 +179,7 @@ export const allServiceDefinitions: ServiceDefinition[] = [
 	rocketchatDefinition,
 	mattermostDefinition,
 	stableDiffusionDefinition,
+	comfyuiDefinition,
 	playwrightServerDefinition,
 	openWebuiDefinition,
 	librechatDefinition,
@@ -178,6 +193,8 @@ export const allServiceDefinitions: ServiceDefinition[] = [
 	watchtowerDefinition,
 	dozzleDefinition,
 	beszelDefinition,
+	convexDefinition,
+	convexDashboardDefinition,
 	claudeCodeDefinition,
 	opencodeDefinition,
 	codexDefinition,
@@ -187,6 +204,8 @@ export const allServiceDefinitions: ServiceDefinition[] = [
 	mixpostDefinition,
 	matomoDefinition,
 	umamiDefinition,
+	usesendDefinition,
+	missionControlDefinition,
 	openpanelDefinition,
 	lightpandaDefinition,
 	steelBrowserDefinition,
@@ -197,4 +216,6 @@ export const allServiceDefinitions: ServiceDefinition[] = [
 	lasuiteMeetBackendDefinition,
 	lasuiteMeetFrontendDefinition,
 	lasuiteMeetAgentsDefinition,
+	desktopEnvironmentDefinition,
+	streamGatewayDefinition,
 ];

package/src/services/definitions/mission-control.ts

@@ -0,0 +1,71 @@
+import type { ServiceDefinition } from "../../types.js";
+
+export const missionControlDefinition: ServiceDefinition = {
+	id: "mission-control",
+	name: "Mission Control",
+	description:
+		"Real-time agent oversight dashboard for OpenClaw. Kanban task board, live activity feed, document browser, and message threads — powered by Convex.",
+	category: "dev-tools",
+	icon: "🛸",
+
+	image: "ghcr.io/bidewio/mission-control",
+	imageTag: "latest",
+	ports: [
+		{
+			host: 3660,
+			container: 3660,
+			description: "Mission Control Web UI",
+			exposed: true,
+		},
+	],
+	volumes: [],
+	environment: [
+		{
+			key: "VITE_CONVEX_URL",
+			defaultValue: "http://127.0.0.1:3210",
+			secret: false,
+			description:
+				"Convex backend URL as seen from the browser (build-time, embedded in JS bundle)",
+			required: true,
+		},
+		{
+			key: "CONVEX_SELF_HOSTED_URL",
+			defaultValue: "http://convex:3210",
+			secret: false,
+			description:
+				"Internal Docker URL for pushing Convex functions during build",
+			required: true,
+		},
+		{
+			key: "CONVEX_SELF_HOSTED_ADMIN_KEY",
+			defaultValue: "",
+			secret: true,
+			description:
+				"Admin key for the self-hosted Convex backend. Generate with: docker compose exec convex ./generate_admin_key.sh",
+			required: true,
+		},
+	],
+	dependsOn: ["convex"],
+	restartPolicy: "unless-stopped",
+	networks: ["openclaw-network"],
+
+	skills: [],
+	openclawEnvVars: [],
+
+	docsUrl:
+		"https://github.com/bidewio/better-openclaw/tree/main/packages/mission-control",
+	selfHostedDocsUrl:
+		"https://github.com/bidewio/better-openclaw/tree/main/packages/mission-control",
+	tags: ["openclaw", "dashboard", "monitoring", "agents", "analytics", "convex"],
+	maturity: "stable",
+
+	requires: ["convex"],
+	recommends: ["convex-dashboard"],
+	conflictsWith: [],
+	mandatory: true,
+	removalWarning:
+		"Mission Control is the primary dashboard for monitoring your OpenClaw agents. Removing it will eliminate real-time agent oversight, task management, and activity tracking.",
+
+	minMemoryMB: 128,
+	gpuRequired: false,
+};