@askexenow/exe-os 0.9.82 → 0.9.84

package/deploy/compose/docker-compose.yml

@@ -0,0 +1,392 @@
+# exe-os VPS stack — full production compose
+#
+# Services: exe-crm + crm-postgres + clickhouse + redis + exe-wiki + exed + exe-gateway
+# Standard for managed customer VPSs: exe-monitor-agent reports fleet health to monitor.askexe.com.
+# All image tags pinned per-client via .env (no :latest). Healthchecks on every service.
+# Named volumes for state; explicit subnets; depends_on with service_healthy gates.
+#
+# Validate without secrets:
+#   cp .env.example .env && docker compose -f docker-compose.yml config
+#
+# Boot stack on a Lane-A-1-provisioned host:
+#   docker compose -f docker-compose.yml up -d
+#
+# nginx snippets at ../nginx/snippets/*.conf are included by the Ansible
+# nginx-tls role from /etc/nginx/snippets/.
+
+name: exe-os
+
+services:
+  # ------------------------------------------------------------------
+  # Data layer
+  # ------------------------------------------------------------------
+
+  crm-postgres:
+    image: postgres:16.6-alpine
+    container_name: crm-postgres
+    restart: unless-stopped
+    env_file:
+      - path: .env
+        required: false
+    environment:
+      POSTGRES_USER: ${POSTGRES_USER:-exe}
+      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD:?POSTGRES_PASSWORD is required}
+      POSTGRES_DB: ${POSTGRES_DB:-default}
+      PGDATA: /var/lib/postgresql/data/pgdata
+    volumes:
+      - postgres_data:/var/lib/postgresql/data
+    networks:
+      backend:
+        ipv4_address: 10.42.0.10
+    healthcheck:
+      test: ["CMD-SHELL", "pg_isready -U ${POSTGRES_USER:-exe} -d ${POSTGRES_DB:-default}"]
+      interval: 10s
+      timeout: 5s
+      start_period: 30s
+      retries: 5
+    logging:
+      driver: json-file
+      options: { max-size: "10m", max-file: "3" }
+
+  clickhouse:
+    image: clickhouse/clickhouse-server:24.8.4.13-alpine
+    container_name: clickhouse
+    restart: unless-stopped
+    env_file:
+      - path: .env
+        required: false
+    environment:
+      CLICKHOUSE_DB: ${CLICKHOUSE_DB:-default}
+      CLICKHOUSE_USER: ${CLICKHOUSE_USER:-exe}
+      CLICKHOUSE_PASSWORD: ${CLICKHOUSE_PASSWORD:?CLICKHOUSE_PASSWORD is required}
+      CLICKHOUSE_DEFAULT_ACCESS_MANAGEMENT: "1"
+    volumes:
+      - clickhouse_data:/var/lib/clickhouse
+      - clickhouse_logs:/var/log/clickhouse-server
+    ulimits:
+      nofile:
+        soft: 262144
+        hard: 262144
+    networks:
+      backend:
+        ipv4_address: 10.42.0.11
+    healthcheck:
+      test: ["CMD", "wget", "--no-verbose", "--tries=1", "--spider", "http://127.0.0.1:8123/ping"]
+      interval: 10s
+      timeout: 5s
+      start_period: 30s
+      retries: 5
+    logging:
+      driver: json-file
+      options: { max-size: "10m", max-file: "3" }
+
+  redis:
+    image: redis:7.4-alpine
+    container_name: redis
+    restart: unless-stopped
+    env_file:
+      - path: .env
+        required: false
+    command: ["redis-server", "--requirepass", "${REDIS_PASSWORD:?REDIS_PASSWORD is required}", "--save", "60", "1", "--appendonly", "yes"]
+    volumes:
+      - redis_data:/data
+    networks:
+      backend:
+        ipv4_address: 10.42.0.12
+    healthcheck:
+      test: ["CMD-SHELL", "redis-cli -a $${REDIS_PASSWORD:?REDIS_PASSWORD is required} ping | grep -q PONG"]
+      interval: 10s
+      timeout: 5s
+      start_period: 10s
+      retries: 5
+    logging:
+      driver: json-file
+      options: { max-size: "10m", max-file: "3" }
+
+  # ------------------------------------------------------------------
+  # Apps
+  # ------------------------------------------------------------------
+
+  exe-crm:
+    image: ${CRM_IMAGE_TAG:-registry.askexe.com/askexe/exe-crm:v0.9.3}
+    container_name: exe-crm
+    restart: unless-stopped
+    depends_on:
+      crm-postgres:
+        condition: service_healthy
+      clickhouse:
+        condition: service_healthy
+      redis:
+        condition: service_healthy
+    env_file:
+      - path: .env
+        required: false
+    environment:
+      NODE_ENV: production
+      NODE_PORT: "3000"
+      EXE_LICENSE_KEY: ${EXE_LICENSE_KEY:?EXE_LICENSE_KEY is required — purchase at https://askexe.com}
+      SERVER_URL: ${CRM_SERVER_URL:-https://crm.askexe.com}
+      APP_SECRET: ${CRM_APP_SECRET:?CRM_APP_SECRET is required}
+      PG_DATABASE_URL: postgres://${POSTGRES_USER:-exe}:${POSTGRES_PASSWORD:?POSTGRES_PASSWORD is required}@crm-postgres:5432/${POSTGRES_DB:-default}
+      REDIS_URL: redis://:${REDIS_PASSWORD:?REDIS_PASSWORD is required}@redis:6379
+      CLICKHOUSE_URL: http://${CLICKHOUSE_USER:-exe}:${CLICKHOUSE_PASSWORD:?CLICKHOUSE_PASSWORD is required}@clickhouse:8123/${CLICKHOUSE_DB:-default}
+      STORAGE_TYPE: local
+      STORAGE_LOCAL_PATH: /app/.local-storage
+      BRANDING_CONFIG_PATH: /app/branding.json
+    ports:
+      - "127.0.0.1:${CRM_HOST_PORT:-3000}:3000"
+    volumes:
+      - crm_data:/app/.local-storage
+      - ${BRANDING_CONFIG:-./branding.json}:/app/branding.json:ro
+    networks:
+      backend:
+        ipv4_address: 10.42.0.20
+      frontend:
+        ipv4_address: 10.43.0.20
+    healthcheck:
+      test: ["CMD", "wget", "--no-verbose", "--tries=1", "--spider", "http://localhost:3000/healthz"]
+      interval: 30s
+      timeout: 5s
+      start_period: 60s
+      retries: 5
+    logging:
+      driver: json-file
+      options: { max-size: "10m", max-file: "3" }
+
+  exe-crm-worker:
+    image: ${CRM_IMAGE_TAG:-registry.askexe.com/askexe/exe-crm:v0.9.3}
+    container_name: exe-crm-worker
+    restart: unless-stopped
+    command: ["yarn", "worker:prod"]
+    depends_on:
+      crm-postgres:
+        condition: service_healthy
+      clickhouse:
+        condition: service_healthy
+      redis:
+        condition: service_healthy
+      exe-crm:
+        condition: service_healthy
+    env_file:
+      - path: .env
+        required: false
+    environment:
+      NODE_ENV: production
+      EXE_LICENSE_KEY: ${EXE_LICENSE_KEY:?EXE_LICENSE_KEY is required — purchase at https://askexe.com}
+      SERVER_URL: ${CRM_SERVER_URL:-https://crm.askexe.com}
+      APP_SECRET: ${CRM_APP_SECRET:?CRM_APP_SECRET is required}
+      PG_DATABASE_URL: postgres://${POSTGRES_USER:-exe}:${POSTGRES_PASSWORD:?POSTGRES_PASSWORD is required}@crm-postgres:5432/${POSTGRES_DB:-default}
+      REDIS_URL: redis://:${REDIS_PASSWORD:?REDIS_PASSWORD is required}@redis:6379
+      CLICKHOUSE_URL: http://${CLICKHOUSE_USER:-exe}:${CLICKHOUSE_PASSWORD:?CLICKHOUSE_PASSWORD is required}@clickhouse:8123/${CLICKHOUSE_DB:-default}
+      STORAGE_TYPE: local
+      STORAGE_LOCAL_PATH: /app/.local-storage
+      BRANDING_CONFIG_PATH: /app/branding.json
+      DISABLE_DB_MIGRATIONS: "true"
+      DISABLE_CRON_JOBS_REGISTRATION: "true"
+    volumes:
+      - crm_data:/app/.local-storage
+      - ${BRANDING_CONFIG:-./branding.json}:/app/branding.json:ro
+    networks:
+      backend:
+        ipv4_address: 10.42.0.24
+    logging:
+      driver: json-file
+      options: { max-size: "10m", max-file: "3" }
+
+  exe-wiki:
+    image: ${WIKI_IMAGE_TAG:-registry.askexe.com/askexe/exe-wiki:v0.9.3}
+    container_name: exe-wiki
+    restart: unless-stopped
+    depends_on:
+      crm-postgres:
+        condition: service_healthy
+    env_file:
+      - path: .env
+        required: false
+    environment:
+      NODE_ENV: production
+      SERVER_PORT: "3001"
+      EXE_LICENSE_KEY: ${EXE_LICENSE_KEY:?EXE_LICENSE_KEY is required — purchase at https://askexe.com}
+      STORAGE_DIR: /app/server/storage
+      DATABASE_URL: postgres://${POSTGRES_USER:-exe}:${POSTGRES_PASSWORD:?POSTGRES_PASSWORD is required}@crm-postgres:5432/${POSTGRES_DB:-default}?schema=${WIKI_DB_SCHEMA:-wiki}
+      AUTH_TOKEN: ${WIKI_AUTH_TOKEN:?WIKI_AUTH_TOKEN is required}
+      JWT_SECRET: ${WIKI_JWT_SECRET:?WIKI_JWT_SECRET is required}
+      SIG_KEY: ${WIKI_SIG_KEY:?WIKI_SIG_KEY is required}
+      SIG_SALT: ${WIKI_SIG_SALT:?WIKI_SIG_SALT is required}
+      VECTOR_DB: ${WIKI_VECTOR_DB:-postgres}
+      BRANDING_CONFIG_PATH: /app/branding.json
+    ports:
+      - "127.0.0.1:${WIKI_HOST_PORT:-3001}:3001"
+    volumes:
+      - wiki_data:/app/server/storage
+      - ${BRANDING_CONFIG:-./branding.json}:/app/branding.json:ro
+    networks:
+      backend:
+        ipv4_address: 10.42.0.21
+      frontend:
+        ipv4_address: 10.43.0.21
+    healthcheck:
+      test: ["CMD", "node", "-e", "const http=require('http');const r=http.get('http://127.0.0.1:3001/api/ping',s=>{process.exit(s.statusCode===200?0:1)});r.on('error',()=>process.exit(1));r.setTimeout(4000,()=>process.exit(1))"]
+      interval: 30s
+      timeout: 5s
+      start_period: 60s
+      retries: 5
+    logging:
+      driver: json-file
+      options: { max-size: "10m", max-file: "3" }
+
+  exed:
+    image: ${EXED_IMAGE_TAG:-registry.askexe.com/askexe/exed:v0.9.7}
+    container_name: exed
+    restart: unless-stopped
+    env_file:
+      - path: .env
+        required: false
+    environment:
+      NODE_ENV: production
+      EXED_PORT: "8765"
+      EXED_HOST: 0.0.0.0
+      EXED_MCP_TOKEN: ${EXED_MCP_TOKEN:?EXED_MCP_TOKEN is required}
+      EXED_DEVICE_ID: ${EXED_DEVICE_ID:-vps-default}
+      EXE_LICENSE_KEY: ${EXE_LICENSE_KEY:?EXE_LICENSE_KEY is required — purchase at https://askexe.com}
+      DATABASE_URL: ${EXED_DATABASE_URL:-postgres://${POSTGRES_USER:-exe}:${POSTGRES_PASSWORD:?POSTGRES_PASSWORD is required}@crm-postgres:5432/${POSTGRES_DB:-default}}
+      EXE_CLOUD_SYNC_TO_POSTGRES: ${EXE_CLOUD_SYNC_TO_POSTGRES:-true}
+      EXE_RSS_WARN_MB: ${EXE_RSS_WARN_MB:-6144}
+      EXE_RSS_RESTART_MB: ${EXE_RSS_RESTART_MB:-8192}
+      EXE_OS_DIR: /home/exed/.exe-os
+    volumes:
+      - exed_data:/home/exed/.exe-os
+    ports:
+      - "127.0.0.1:${EXED_HOST_PORT:-8765}:8765"
+    networks:
+      backend:
+        ipv4_address: 10.42.0.22
+    healthcheck:
+      test: ["CMD", "node", "-e", "const http=require('http');const r=http.get('http://127.0.0.1:8765/health',s=>{process.exit(s.statusCode===200?0:1)});r.on('error',()=>process.exit(1));r.setTimeout(4000,()=>process.exit(1))"]
+      interval: 30s
+      timeout: 5s
+      start_period: 30s
+      retries: 5
+    logging:
+      driver: json-file
+      options: { max-size: "10m", max-file: "3" }
+
+  exe-gateway:
+    image: ${GATEWAY_IMAGE_TAG:-registry.askexe.com/askexe/exe-gateway:v0.9.3}
+    container_name: exe-gateway
+    restart: unless-stopped
+    depends_on:
+      exed:
+        condition: service_healthy
+    env_file:
+      - path: .env
+        required: false
+    environment:
+      NODE_ENV: production
+      EXE_GATEWAY_HOME: /data
+      EXE_GATEWAY_CONFIG: /data/gateway.json
+      EXE_GATEWAY_PORT: "3100"
+      EXE_GATEWAY_HOST: 0.0.0.0
+      EXE_GATEWAY_AUTH_TOKEN: ${EXE_GATEWAY_AUTH_TOKEN:?EXE_GATEWAY_AUTH_TOKEN is required}
+      EXE_GATEWAY_WHATSAPP_VERIFY_TOKEN: ${EXE_GATEWAY_WHATSAPP_VERIFY_TOKEN:?EXE_GATEWAY_WHATSAPP_VERIFY_TOKEN is required}
+      EXE_GATEWAY_WS_RELAY_ENABLED: "true"
+      EXE_GATEWAY_WS_RELAY_HOST: 0.0.0.0
+      EXE_GATEWAY_WS_RELAY_PORT: "3101"
+      EXE_GATEWAY_WS_RELAY_AUTH_TOKEN: ${EXE_GATEWAY_WS_RELAY_AUTH_TOKEN:?EXE_GATEWAY_WS_RELAY_AUTH_TOKEN is required}
+      WHATSAPP_ACCESS_TOKEN: ${WHATSAPP_ACCESS_TOKEN:-}
+      API_ROUTER_URL: ${API_ROUTER_URL:-https://gateway.askexe.com}
+      API_ROUTER_KEY: ${API_ROUTER_KEY:-}
+      BYOK_ENABLED: ${BYOK_ENABLED:-false}
+      ANTHROPIC_API_KEY: ${ANTHROPIC_API_KEY:-}
+      EXE_LICENSE_KEY: ${EXE_LICENSE_KEY:?EXE_LICENSE_KEY is required — purchase at https://askexe.com}
+    ports:
+      - "127.0.0.1:${GATEWAY_HTTP_HOST_PORT:-3100}:3100"
+      - "127.0.0.1:${GATEWAY_WS_HOST_PORT:-3101}:3101"
+    volumes:
+      - gateway_data:/data
+      - ./gateway.json:/data/gateway.json:ro
+    networks:
+      backend:
+        ipv4_address: 10.42.0.23
+      frontend:
+        ipv4_address: 10.43.0.23
+    healthcheck:
+      test: ["CMD", "node", "-e", "const http=require('http');const r=http.get('http://localhost:3100/health',s=>{process.exit(s.statusCode===200?0:1)});r.on('error',()=>process.exit(1));r.setTimeout(4000,()=>process.exit(1))"]
+      interval: 30s
+      timeout: 5s
+      start_period: 30s
+      retries: 5
+    logging:
+      driver: json-file
+      options: { max-size: "10m", max-file: "3" }
+
+  exe-monitor-agent:
+    image: ${MONITOR_AGENT_IMAGE_TAG:-registry.askexe.com/askexe/exe-monitor-agent:v0.9.3}
+    container_name: exe-monitor-agent
+    restart: unless-stopped
+    environment:
+      HUB_URL: ${MONITOR_HUB_URL:-https://monitor.askexe.com}
+      TOKEN: ${MONITOR_AGENT_TOKEN:?MONITOR_AGENT_TOKEN is required — create Hygo system in monitor.askexe.com}
+      KEY: ${MONITOR_AGENT_KEY:?MONITOR_AGENT_KEY is required — copy public key from monitor.askexe.com}
+      LISTEN: ${MONITOR_AGENT_LISTEN:-:45876}
+    volumes:
+      - /var/run/docker.sock:/var/run/docker.sock:ro
+      - /proc:/host/proc:ro
+      - /sys:/host/sys:ro
+      - /etc/os-release:/host/etc/os-release:ro
+      - monitor_agent_data:/var/lib/beszel-agent
+    networks:
+      backend:
+        ipv4_address: 10.42.0.30
+    healthcheck:
+      test: ["CMD", "/agent", "health"]
+      interval: 30s
+      timeout: 5s
+      start_period: 30s
+      retries: 5
+    logging:
+      driver: json-file
+      options: { max-size: "10m", max-file: "3" }
+
+# ------------------------------------------------------------------
+# Volumes
+# ------------------------------------------------------------------
+volumes:
+  postgres_data:
+    driver: local
+  clickhouse_data:
+    driver: local
+  clickhouse_logs:
+    driver: local
+  redis_data:
+    driver: local
+  crm_data:
+    driver: local
+  wiki_data:
+    driver: local
+  exed_data:
+    driver: local
+  gateway_data:
+    driver: local
+  monitor_agent_data:
+    driver: local
+
+# ------------------------------------------------------------------
+# Networks
+# ------------------------------------------------------------------
+# backend  — internal service-to-service traffic (DBs + apps)
+# frontend — exposed to host nginx via published ports on apps that
+#            terminate user traffic (CRM, wiki, gateway). DBs never touch this net.
+networks:
+  backend:
+    driver: bridge
+    ipam:
+      driver: default
+      config:
+        - subnet: 10.42.0.0/24
+  frontend:
+    driver: bridge
+    ipam:
+      driver: default
+      config:
+        - subnet: 10.43.0.0/24

package/deploy/compose/gateway.json

@@ -0,0 +1 @@
+{}

package/deploy/compose/generate-env.ts

@@ -0,0 +1,252 @@
+import { randomBytes } from "node:crypto";
+const REGISTRY = "ghcr.io/askexe";
+
+// v0.9.x is the private/customer pilot stack line. Component repos keep their
+// own package semver internally, but customer deployments use the tested stack
+// image alias so one stack manifest can pin the whole release. exe-os/exed is
+// the exception because the runtime package version is the orchestrator release.
+const STACK_IMAGE_TAG = "v0.9.2";
+const EXED_RELEASE_TAG = "v0.9.2";
+
+const POSTGRES_USER = "exe";
+const POSTGRES_DB = "default";
+const CLICKHOUSE_DB = "default";
+const CLICKHOUSE_USER = "exe";
+export const CRM_IMAGE_TAG = `${REGISTRY}/exe-crm:${STACK_IMAGE_TAG}`;
+const CRM_HOST_PORT = "3000";
+export const WIKI_IMAGE_TAG = `${REGISTRY}/exe-wiki:${STACK_IMAGE_TAG}`;
+const WIKI_DB_SCHEMA = "wiki";
+const WIKI_VECTOR_DB = "postgres";
+const WIKI_HOST_PORT = "3001";
+export const EXED_IMAGE_TAG = `${REGISTRY}/exed:${EXED_RELEASE_TAG}`;
+export const GATEWAY_IMAGE_TAG = `${REGISTRY}/exe-gateway:${STACK_IMAGE_TAG}`;
+export const MONITOR_AGENT_IMAGE_TAG = `${REGISTRY}/exe-monitor-agent:${STACK_IMAGE_TAG}`;
+const GATEWAY_HTTP_HOST_PORT = "3100";
+const GATEWAY_WS_HOST_PORT = "3101";
+const RANDOM_SECRET_16 = 16;
+const RANDOM_SECRET_32 = 32;
+const RANDOM_SECRET_48 = 48;
+const LICENSE_KEY_COMMENT = "# injected by deploy_client";
+const MANUAL_VALUE_COMMENT = "# SET_MANUALLY";
+const EXAMPLE_LICENSE_KEY = "CHANGEME_EXE_LICENSE_KEY";
+const DEFAULT_API_ROUTER_URL = "https://gateway.askexe.com";
+const DEFAULT_MONITOR_HUB_URL = "https://monitor.askexe.com";
+const DEFAULT_MONITOR_AGENT_LISTEN = ":45876";
+
+export interface GenerateEnvOptions {
+  clientName: string;
+  domain: string;
+  licenseKey?: string;
+}
+
+export function generateEnv(options: GenerateEnvOptions): string {
+  const normalizedDomain = normalizeDomain(options.domain);
+  const normalizedClientName = normalizeClientName(options.clientName);
+  const gatewayWsAuthToken = randomSecret(RANDOM_SECRET_48);
+
+  return joinEnvLines([
+    "# --- Data Layer ---",
+    `POSTGRES_USER=${POSTGRES_USER}`,
+    `POSTGRES_PASSWORD=${randomSecret(RANDOM_SECRET_32)}`,
+    `POSTGRES_DB=${POSTGRES_DB}`,
+    "",
+    `CLICKHOUSE_DB=${CLICKHOUSE_DB}`,
+    `CLICKHOUSE_USER=${CLICKHOUSE_USER}`,
+    `CLICKHOUSE_PASSWORD=${randomSecret(RANDOM_SECRET_32)}`,
+    "",
+    `REDIS_PASSWORD=${randomSecret(RANDOM_SECRET_32)}`,
+    "",
+    "# --- CRM ---",
+    `CRM_IMAGE_TAG=${CRM_IMAGE_TAG}`,
+    `CRM_SERVER_URL=https://${normalizedDomain}`,
+    `CRM_APP_SECRET=${randomSecret(RANDOM_SECRET_48)}`,
+    `CRM_HOST_PORT=${CRM_HOST_PORT}`,
+    "",
+    "# --- Wiki ---",
+    `WIKI_IMAGE_TAG=${WIKI_IMAGE_TAG}`,
+    `WIKI_DB_SCHEMA=${WIKI_DB_SCHEMA}`,
+    `WIKI_VECTOR_DB=${WIKI_VECTOR_DB}`,
+    `WIKI_AUTH_TOKEN=${randomSecret(RANDOM_SECRET_48)}`,
+    `WIKI_JWT_SECRET=${randomSecret(RANDOM_SECRET_48)}`,
+    `WIKI_SIG_KEY=${randomSecret(RANDOM_SECRET_48)}`,
+    `WIKI_SIG_SALT=${randomSecret(RANDOM_SECRET_16)}`,
+    `WIKI_HOST_PORT=${WIKI_HOST_PORT}`,
+    "",
+    "# --- exed ---",
+    `EXED_IMAGE_TAG=${EXED_IMAGE_TAG}`,
+    `EXED_MCP_TOKEN=${randomSecret(RANDOM_SECRET_48)}`,
+    `EXED_DEVICE_ID=vps-${normalizedClientName}`,
+    "# VPS-only: enables cloud/local SQLite -> exe-db Postgres projection.",
+    "EXE_CLOUD_SYNC_TO_POSTGRES=true",
+    "",
+    "# --- Gateway ---",
+    `GATEWAY_IMAGE_TAG=${GATEWAY_IMAGE_TAG}`,
+    `EXE_GATEWAY_AUTH_TOKEN=${randomSecret(RANDOM_SECRET_48)}`,
+    `EXE_GATEWAY_WS_RELAY_AUTH_TOKEN=${gatewayWsAuthToken}`,
+    `EXE_GATEWAY_WHATSAPP_VERIFY_TOKEN=${randomSecret(RANDOM_SECRET_32)}`,
+    MANUAL_VALUE_COMMENT,
+    "WHATSAPP_ACCESS_TOKEN=",
+    `API_ROUTER_URL=${DEFAULT_API_ROUTER_URL}`,
+    `API_ROUTER_KEY=exe_rk_${randomSecret(48)}`,
+    "# BYOK: to use your own API keys instead of the Exe API Router,",
+    "# set BYOK_ENABLED=true and provide ANTHROPIC_API_KEY below.",
+    "# BYOK_ENABLED=false",
+    "# ANTHROPIC_API_KEY=",
+    `GATEWAY_HTTP_HOST_PORT=${GATEWAY_HTTP_HOST_PORT}`,
+    `GATEWAY_WS_HOST_PORT=${GATEWAY_WS_HOST_PORT}`,
+    "",
+    "# --- Monitoring agent (standard for managed customer VPSs) ---",
+    `MONITOR_AGENT_IMAGE_TAG=${MONITOR_AGENT_IMAGE_TAG}`,
+    `MONITOR_HUB_URL=${DEFAULT_MONITOR_HUB_URL}`,
+    "MONITOR_AGENT_TOKEN=CHANGEME_MONITOR_AGENT_TOKEN_FROM_MONITOR_HUB",
+    "MONITOR_AGENT_KEY=CHANGEME_MONITOR_AGENT_PUBLIC_KEY_FROM_MONITOR_HUB",
+    `MONITOR_AGENT_LISTEN=${DEFAULT_MONITOR_AGENT_LISTEN}`,
+    "",
+    "# --- License ---",
+    LICENSE_KEY_COMMENT,
+    `EXE_LICENSE_KEY=${options.licenseKey ?? EXAMPLE_LICENSE_KEY}`,
+  ]);
+}
+
+export function generateExampleEnv(): string {
+  return joinEnvLines([
+    "# exe-os VPS stack — example environment variables",
+    "# Copy to .env before deployment and replace every CHANGEME_* value.",
+    "# Values under # SET_MANUALLY must be provided by the operator.",
+    "",
+    "# --- Data Layer ---",
+    `POSTGRES_USER=${POSTGRES_USER}`,
+    "POSTGRES_PASSWORD=CHANGEME_POSTGRES_PASSWORD",
+    `POSTGRES_DB=${POSTGRES_DB}`,
+    "",
+    `CLICKHOUSE_DB=${CLICKHOUSE_DB}`,
+    `CLICKHOUSE_USER=${CLICKHOUSE_USER}`,
+    "CLICKHOUSE_PASSWORD=CHANGEME_CLICKHOUSE_PASSWORD",
+    "",
+    "REDIS_PASSWORD=CHANGEME_REDIS_PASSWORD",
+    "",
+    "# --- CRM ---",
+    `CRM_IMAGE_TAG=${CRM_IMAGE_TAG}`,
+    "CRM_SERVER_URL=https://CHANGEME_DOMAIN",
+    "CRM_APP_SECRET=CHANGEME_CRM_APP_SECRET",
+    `CRM_HOST_PORT=${CRM_HOST_PORT}`,
+    "",
+    "# --- Wiki ---",
+    `WIKI_IMAGE_TAG=${WIKI_IMAGE_TAG}`,
+    `WIKI_DB_SCHEMA=${WIKI_DB_SCHEMA}`,
+    `WIKI_VECTOR_DB=${WIKI_VECTOR_DB}`,
+    "WIKI_AUTH_TOKEN=CHANGEME_WIKI_AUTH_TOKEN",
+    "WIKI_JWT_SECRET=CHANGEME_WIKI_JWT_SECRET",
+    "WIKI_SIG_KEY=CHANGEME_WIKI_SIG_KEY",
+    "WIKI_SIG_SALT=CHANGEME_WIKI_SIG_SALT",
+    `WIKI_HOST_PORT=${WIKI_HOST_PORT}`,
+    "",
+    "# --- exed ---",
+    `EXED_IMAGE_TAG=${EXED_IMAGE_TAG}`,
+    "EXED_MCP_TOKEN=CHANGEME_EXED_MCP_TOKEN",
+    "EXED_DEVICE_ID=vps-default",
+    "# VPS-only: enables cloud/local SQLite -> exe-db Postgres projection.",
+    "# Keep false on laptops/dev boxes.",
+    "EXE_CLOUD_SYNC_TO_POSTGRES=true",
+    "",
+    "# --- Gateway ---",
+    `GATEWAY_IMAGE_TAG=${GATEWAY_IMAGE_TAG}`,
+    "EXE_GATEWAY_AUTH_TOKEN=CHANGEME_EXE_GATEWAY_AUTH_TOKEN",
+    "EXE_GATEWAY_WS_RELAY_AUTH_TOKEN=CHANGEME_EXE_GATEWAY_WS_RELAY_AUTH_TOKEN",
+    "EXE_GATEWAY_WHATSAPP_VERIFY_TOKEN=CHANGEME_EXE_GATEWAY_WHATSAPP_VERIFY_TOKEN",
+    MANUAL_VALUE_COMMENT,
+    "WHATSAPP_ACCESS_TOKEN=",
+    `API_ROUTER_URL=${DEFAULT_API_ROUTER_URL}`,
+    "API_ROUTER_KEY=exe_rk_CHANGEME_API_ROUTER_KEY",
+    "# BYOK: to use your own API keys instead of the Exe API Router,",
+    "# set BYOK_ENABLED=true and provide ANTHROPIC_API_KEY below.",
+    "# BYOK_ENABLED=false",
+    "# ANTHROPIC_API_KEY=CHANGEME_ANTHROPIC_API_KEY",
+    `GATEWAY_HTTP_HOST_PORT=${GATEWAY_HTTP_HOST_PORT}`,
+    `GATEWAY_WS_HOST_PORT=${GATEWAY_WS_HOST_PORT}`,
+    "",
+    "# --- Monitoring agent (standard for managed customer VPSs) ---",
+    `MONITOR_AGENT_IMAGE_TAG=${MONITOR_AGENT_IMAGE_TAG}`,
+    `MONITOR_HUB_URL=${DEFAULT_MONITOR_HUB_URL}`,
+    "# Values copied from monitor.askexe.com when adding a new system.",
+    "MONITOR_AGENT_TOKEN=CHANGEME_MONITOR_AGENT_TOKEN_FROM_MONITOR_HUB",
+    "MONITOR_AGENT_KEY=CHANGEME_MONITOR_AGENT_PUBLIC_KEY_FROM_MONITOR_HUB",
+    `MONITOR_AGENT_LISTEN=${DEFAULT_MONITOR_AGENT_LISTEN}`,
+    "",
+    "# --- AskExe central monitoring hub auth (AskExe-owned infra only) ---",
+    "# Customer VPSs normally run only MONITOR_AGENT_* above. These hub values are",
+    "# for monitor.askexe.com on exe-db-jkt.",
+    "MONITOR_HUB_PUBLIC_URL=https://monitor.askexe.com",
+    "MONITOR_HUB_SOURCE_DIR=/opt/exe-monitor",
+    "MONITOR_HUB_HOST_PORT=8090",
+    "MONITOR_HUB_DATA_DIR=/opt/exe-monitor-data",
+    "MONITOR_TRUSTED_AUTH_HEADER=X-AskExe-User-Email",
+    "# Keep false during bootstrap; flip true after the GoTrue auth proxy is live.",
+    "MONITOR_DISABLE_PASSWORD_AUTH=false",
+    "MONITOR_USER_CREATION=true",
+    "MONITOR_SHARE_ALL_SYSTEMS=false",
+    "",
+    "# --- License ---",
+    LICENSE_KEY_COMMENT,
+    `EXE_LICENSE_KEY=${EXAMPLE_LICENSE_KEY}`,
+  ]);
+}
+
+export function randomSecret(length: number): string {
+  return randomBytes(Math.ceil(length / 2)).toString("hex").slice(0, length);
+}
+
+function normalizeDomain(domain: string): string {
+  return domain.trim().replace(/^https?:\/\//, "").replace(/\/+$/, "");
+}
+
+function normalizeClientName(clientName: string): string {
+  return clientName
+    .trim()
+    .toLowerCase()
+    .replace(/[^a-z0-9-]/g, "-")
+    .replace(/-+/g, "-")
+    .replace(/^-|-$/g, "") || "client";
+}
+
+function joinEnvLines(lines: string[]): string {
+  return `${lines.join("\n")}\n`;
+}
+
+function printUsage(): void {
+  process.stderr.write(
+    "Usage:\n" +
+      "  npx tsx deploy/compose/generate-env.ts <client-name> <domain> [license-key]\n" +
+      "  npx tsx deploy/compose/generate-env.ts --example\n",
+  );
+}
+
+function isCliInvocation(): boolean {
+  return process.argv[1]?.endsWith("generate-env.ts") === true || process.argv[1]?.endsWith("generate-env.js") === true;
+}
+
+function main(): void {
+  const args = process.argv.slice(2);
+
+  if (args.includes("--help") || args.includes("-h")) {
+    printUsage();
+    process.exit(0);
+  }
+
+  if (args.includes("--example")) {
+    process.stdout.write(generateExampleEnv());
+    return;
+  }
+
+  const [clientName, domain, licenseKey] = args;
+  if (!clientName || !domain) {
+    printUsage();
+    process.exit(1);
+  }
+
+  process.stdout.write(generateEnv({ clientName, domain, licenseKey }));
+}
+
+if (isCliInvocation()) {
+  main();
+}