Merge pull request #1539 from mnfst/chore/remove-local-mode

chore: remove local mode (sql.js, MANIFEST_MODE, manifest plugin)

Author: brunobuddy

.changeset/remove-local-mode.md

@@ -0,0 +1,13 @@
+---
+"manifest-model-router": patch
+---
+
+Remove local mode and harden the Docker deployment.
+
+Manifest now runs exclusively on PostgreSQL with Better Auth. The self-contained `manifest` OpenClaw plugin (embedded Nest server, SQLite via sql.js, loopback-trust auth) is deprecated and removed from the repository — it will receive no further releases. Self-hosted users should use the Docker image (`manifestdotbuild/manifest`) with the bundled Postgres container via `docker/docker-compose.yml`, or the cloud version at app.manifest.build.
+
+Docker deployments now default to `NODE_ENV=production`, with migrations controlled by a new `AUTO_MIGRATE=true` env var instead of the previous `NODE_ENV=development` workaround. Production-mode defaults activate: `trust proxy` for reverse-proxied deployments, sanitized upstream error messages, no "Dev" badge in the header, and email verification enforcement when a provider is configured. Self-hosters upgrading must set `BETTER_AUTH_SECRET` via `docker/.env` — the compose file no longer ships a placeholder secret.
+
+New unified `EMAIL_*` env var scheme (`EMAIL_PROVIDER`, `EMAIL_API_KEY`, `EMAIL_DOMAIN`, `EMAIL_FROM`) covers both Better Auth transactional emails (signup verification, password reset) and threshold alert notifications. Supports Resend (recommended for self-hosting — no domain setup), Mailgun, and SendGrid. Legacy `MAILGUN_*` env vars still work for backward compatibility.
+
+Breaking: `MANIFEST_MODE`, `MANIFEST_DB_PATH`, `MANIFEST_UPDATE_CHECK_OPTOUT`, `MANIFEST_TRUST_LAN` env vars are removed (no-op if set). The `manifest` npm package is deprecated. The `manifest-model-router` plugin is unaffected and remains the recommended way to route OpenClaw requests through Manifest.

.github/workflows/ci.yml

@@ -69,32 +69,6 @@ jobs:
           directory: packages/backend/coverage
           fail_ci_if_error: false
 
-  backend-sqljs:
-    name: Backend (sql.js / ${{ matrix.os }})
-    runs-on: ${{ matrix.os }}
-    strategy:
-      matrix:
-        os: [ubuntu-latest, macos-latest]
-
-    env:
-      MANIFEST_MODE: local
-      BETTER_AUTH_SECRET: ci-test-secret-at-least-32-characters-long!!
-      NODE_ENV: test
-
-    steps:
-      - uses: actions/checkout@v4
-      - uses: actions/setup-node@v4
-        with:
-          node-version: 22
-          cache: npm
-      - run: npm ci
-      - run: npm run build --workspace=packages/shared
-      - run: npm run build --workspace=packages/backend
-      - name: Unit tests (sql.js dialect)
-        run: npm test --workspace=packages/backend
-      - name: E2E tests (sql.js in-memory)
-        run: npm run test:e2e --workspace=packages/backend
-
   frontend:
     runs-on: ubuntu-latest
     steps:

.gitignore

@@ -4,6 +4,8 @@ dist/
 build/
 *.log
 .env*
+!.env.example
+!docker/.env.example
 .DS_Store
 Thumbs.db
 *.tmp

docker/.env.example

@@ -0,0 +1,62 @@
+# ─── Required ──────────────────────────────────────────────────────────────
+
+# Session signing secret. Generate with: openssl rand -hex 32
+BETTER_AUTH_SECRET=
+
+
+# ─── Deployment URL ────────────────────────────────────────────────────────
+
+# Override when deploying to a domain (e.g., https://manifest.example.com).
+# Default: http://localhost:3001
+# BETTER_AUTH_URL=http://localhost:3001
+
+
+# ─── Database ──────────────────────────────────────────────────────────────
+
+# Override the bundled Postgres password for hardening.
+# POSTGRES_PASSWORD=change-me
+
+
+# ─── Email provider (optional) ─────────────────────────────────────────────
+#
+# Unified config — used for BOTH login emails (signup verification, password
+# reset) AND threshold alert notifications. Set ONE provider block below.
+#
+# Without any email provider:
+#   - Signup verification is waived (users created as unverified-but-usable)
+#   - Password reset silently no-ops (use DB admin to reset)
+#   - Threshold alerts still work if you configure per-user in the dashboard
+#
+# Per-user providers configured in the dashboard always take precedence over
+# these server-wide defaults, so cloud multi-tenant setups can still use
+# per-user config on top of a shared fallback.
+
+# Option A: Resend (recommended for self-hosting — no domain setup required)
+# Sign up at https://resend.com, create an API key, and set:
+# EMAIL_PROVIDER=resend
+# EMAIL_API_KEY=re_your_api_key_here
+# EMAIL_FROM=noreply@yourdomain.com
+
+# Option B: Mailgun (requires a verified sending domain)
+# EMAIL_PROVIDER=mailgun
+# EMAIL_API_KEY=key-your_api_key_here
+# EMAIL_DOMAIN=mg.yourdomain.com
+# EMAIL_FROM=noreply@mg.yourdomain.com
+
+# Option C: SendGrid
+# EMAIL_PROVIDER=sendgrid
+# EMAIL_API_KEY=SG.your_api_key_here
+# EMAIL_FROM=noreply@yourdomain.com
+
+
+# ─── OAuth logins (optional) ───────────────────────────────────────────────
+#
+# Each provider activates automatically when both CLIENT_ID and CLIENT_SECRET
+# are set. Configure callback URL to: ${BETTER_AUTH_URL}/api/auth/callback/<provider>
+
+# GOOGLE_CLIENT_ID=
+# GOOGLE_CLIENT_SECRET=
+# GITHUB_CLIENT_ID=
+# GITHUB_CLIENT_SECRET=
+# DISCORD_CLIENT_ID=
+# DISCORD_CLIENT_SECRET=

docker/Dockerfile

@@ -25,11 +25,7 @@ COPY packages/backend/package.json packages/backend/
 RUN --mount=type=cache,target=/root/.npm npm ci --omit=dev --ignore-scripts && \
     rm -rf node_modules/typescript node_modules/@types \
            node_modules/ts-node node_modules/acorn \
-           node_modules/create-require node_modules/v8-compile-cache-lib \
-           node_modules/sql.js/dist/sql-asm* \
-           node_modules/sql.js/dist/worker.* \
-           node_modules/sql.js/dist/sql-wasm-browser* \
-           node_modules/sql.js/dist/sql-wasm-debug* && \
+           node_modules/create-require node_modules/v8-compile-cache-lib && \
     find . -path "*/node_modules/vitest" -type d -exec rm -rf {} + 2>/dev/null; \
     find . -path "*/node_modules/vite-node" -type d -exec rm -rf {} + 2>/dev/null; \
     find . -path "*/node_modules/rollup" -type d -exec rm -rf {} + 2>/dev/null; \

docker/docker-compose.yml

@@ -4,6 +4,8 @@
 #     with: openssl rand -hex 32
 #   - Set SEED_DATA=false to stop seeding the demo agent on every boot.
 #   - Change the seeded admin password (admin@manifest.build / manifest).
+#   - Set NODE_ENV=production to enable trust proxy, error sanitization,
+#     and strict Better Auth verification.
 
 services:
   manifest:
@@ -17,7 +19,21 @@ services:
       - BETTER_AUTH_URL=http://localhost:3001
       - SEED_DATA=true
       - NODE_ENV=development
-      - MANIFEST_TRUST_LAN=true
+      - AUTO_MIGRATE=true
+      # Email provider (optional). Covers both login/verification emails
+      # and threshold alert notifications. Set one provider block — see
+      # DOCKER_README.md "Email setup". Supports resend, mailgun, sendgrid.
+      - EMAIL_PROVIDER=${EMAIL_PROVIDER:-}
+      - EMAIL_API_KEY=${EMAIL_API_KEY:-}
+      - EMAIL_DOMAIN=${EMAIL_DOMAIN:-}
+      - EMAIL_FROM=${EMAIL_FROM:-}
+      # OAuth providers (optional). Activate when both ID and SECRET are set.
+      - GOOGLE_CLIENT_ID=${GOOGLE_CLIENT_ID:-}
+      - GOOGLE_CLIENT_SECRET=${GOOGLE_CLIENT_SECRET:-}
+      - GITHUB_CLIENT_ID=${GITHUB_CLIENT_ID:-}
+      - GITHUB_CLIENT_SECRET=${GITHUB_CLIENT_SECRET:-}
+      - DISCORD_CLIENT_ID=${DISCORD_CLIENT_ID:-}
+      - DISCORD_CLIENT_SECRET=${DISCORD_CLIENT_SECRET:-}
     depends_on:
       postgres:
         condition: service_healthy

packages/backend/.env.example

@@ -12,7 +12,8 @@ BETTER_AUTH_URL=http://localhost:3001
 # FRONTEND_PORT=             # Extra trusted origin port for Better Auth
 
 # ── Database ─────────────────────────────────────────
-# DB_POOL_MAX=20            # PostgreSQL connection pool size (default: 20)
+# AUTO_MIGRATE=true          # Run TypeORM migrations on startup (dev/test auto-run; set true for self-hosted prod first boot)
+# DB_POOL_MAX=20             # PostgreSQL connection pool size (default: 20)
 
 # ── Rate Limiting ────────────────────────────────────
 # THROTTLE_TTL=60000         # Rate limit window in ms (default: 60000)
@@ -21,11 +22,35 @@ BETTER_AUTH_URL=http://localhost:3001
 # ── API Key (optional) ──────────────────────────────
 # API_KEY=                   # Secret for programmatic access via X-API-Key header
 
-# ── Email / Mailgun (optional) ──────────────────────
-# Required for email verification and password reset.
-# Without these, the app runs but emails are silently skipped.
-# MAILGUN_API_KEY=           # Starts with key-
-# MAILGUN_DOMAIN=            # e.g. mg.manifest.build
+# ── Email provider (optional, unified) ──────────────
+# Used for BOTH Better Auth transactional emails (login verification,
+# password reset) and threshold alert notifications when no per-user
+# config exists. Set ONE provider block below.
+#
+# Without any email provider: signup verification waived, password reset
+# no-ops. Threshold alerts still work if users configure their own provider
+# in the dashboard Notifications → Email Provider.
+
+# Option A: Resend (recommended — no domain setup required)
+# EMAIL_PROVIDER=resend
+# EMAIL_API_KEY=re_your_api_key_here
+# EMAIL_FROM=noreply@yourdomain.com
+
+# Option B: Mailgun
+# EMAIL_PROVIDER=mailgun
+# EMAIL_API_KEY=key-your_api_key_here
+# EMAIL_DOMAIN=mg.yourdomain.com
+# EMAIL_FROM=noreply@mg.yourdomain.com
+
+# Option C: SendGrid
+# EMAIL_PROVIDER=sendgrid
+# EMAIL_API_KEY=SG.your_api_key_here
+# EMAIL_FROM=noreply@yourdomain.com
+
+# ── Legacy Mailgun (deprecated, use EMAIL_* instead) ─
+# Still honored for backward compat with older deployments.
+# MAILGUN_API_KEY=
+# MAILGUN_DOMAIN=
 # NOTIFICATION_FROM_EMAIL=noreply@manifest.build
 
 # ── OAuth Providers (all optional) ──────────────────
@@ -45,16 +70,11 @@ BETTER_AUTH_URL=http://localhost:3001
 # DISCORD_CLIENT_SECRET=
 
 # ── Plugin ──────────────────────────────────────────
-# PLUGIN_OTLP_ENDPOINT=     # Custom OTLP endpoint for the plugin
+# PLUGIN_OTLP_ENDPOINT=       # Custom OTLP endpoint for the plugin
 
 # ── Data Seeding ────────────────────────────────────
-# SEED_DATA=true             # Seed demo data on startup
-
-# ── Mode (local development) ────────────────────────
-# MANIFEST_MODE=local        # 'local' (SQLite + loopback auth) or 'cloud' (default, PostgreSQL + Better Auth)
-# MANIFEST_DB_PATH=          # SQLite file path for local mode (default: in-memory)
-# MANIFEST_FRONTEND_DIR=     # Custom path to frontend dist directory
-# MANIFEST_EMBEDDED=         # Set to skip auto-start (used by embedded server)
+# SEED_DATA=true              # Seed demo data + admin user on startup (self-hosted first boot)
 
-# ── Update Check ──────────────────────────────────────
-# MANIFEST_UPDATE_CHECK_OPTOUT=1  # Set to '1' to disable npm version checks in local mode
+# ── Internal ────────────────────────────────────────
+# MANIFEST_FRONTEND_DIR=      # Custom path to frontend dist directory
+# MANIFEST_EMBEDDED=          # Set to skip auto-start (used by embedded server)

packages/backend/package.json

@@ -43,7 +43,6 @@
     "react-dom": "^19.2.4",
     "reflect-metadata": "^0.2.0",
     "rxjs": "^7.8.0",
-    "sql.js": "^1.12.0",
     "typeorm": "^0.3.0",
     "uuid": "^11.0.0"
   },

packages/backend/src/analytics/controllers/agents.controller.spec.ts

@@ -1,23 +1,15 @@
-jest.mock('../../common/constants/local-mode.constants', () => ({
-  readLocalApiKey: jest.fn().mockReturnValue(null),
-  LOCAL_AGENT_NAME: 'local-agent',
-}));
-
 import { Test, TestingModule } from '@nestjs/testing';
 import { CACHE_MANAGER, CacheModule } from '@nestjs/cache-manager';
 import { ConfigService } from '@nestjs/config';
 import type { Cache } from 'cache-manager';
-import { BadRequestException, ConflictException, ForbiddenException } from '@nestjs/common';
+import { BadRequestException, ConflictException } from '@nestjs/common';
 import { QueryFailedError } from 'typeorm';
 import { AgentsController } from './agents.controller';
 import { TimeseriesQueriesService } from '../services/timeseries-queries.service';
 import { AgentLifecycleService } from '../services/agent-lifecycle.service';
 import { ApiKeyGeneratorService } from '../../otlp/services/api-key.service';
-import { readLocalApiKey } from '../../common/constants/local-mode.constants';
 import { TenantCacheService } from '../../common/services/tenant-cache.service';
 
-const mockReadLocalApiKey = readLocalApiKey as jest.MockedFunction<typeof readLocalApiKey>;
-
 describe('AgentsController', () => {
   let controller: AgentsController;
   let cacheManager: Cache;
@@ -29,13 +21,6 @@ describe('AgentsController', () => {
   let mockRenameAgent: jest.Mock;
   let mockTenantResolve: jest.Mock;
 
-  const origMode = process.env['MANIFEST_MODE'];
-
-  afterEach(() => {
-    if (origMode === undefined) delete process.env['MANIFEST_MODE'];
-    else process.env['MANIFEST_MODE'] = origMode;
-  });
-
   beforeEach(async () => {
     mockGetAgentList = jest.fn().mockResolvedValue([
       { agent_name: 'bot-1', agent_id: 'id-1', message_count: 100 },
@@ -113,15 +98,15 @@ describe('AgentsController', () => {
     expect(mockGetKeyForAgent).toHaveBeenCalledWith('u1', 'bot-1');
   });
 
-  it('returns full apiKey in local mode for default agent', async () => {
-    mockReadLocalApiKey.mockReturnValue('mnfst_full_local_key');
-    mockConfigGet.mockImplementation((key: string, fallback?: string) =>
-      key === 'MANIFEST_MODE' ? 'local' : (fallback ?? ''),
-    );
+  it('returns full apiKey when service returns fullKey', async () => {
+    mockGetKeyForAgent.mockResolvedValueOnce({
+      keyPrefix: 'mnfst_test1234',
+      fullKey: 'mnfst_full_decrypted',
+    });
     const user = { id: 'u1' };
-    const result = await controller.getAgentKey(user as never, 'local-agent');
+    const result = await controller.getAgentKey(user as never, 'bot-1');
 
-    expect(result).toMatchObject({ keyPrefix: 'mnfst_test1234', apiKey: 'mnfst_full_local_key' });
+    expect(result).toMatchObject({ keyPrefix: 'mnfst_test1234', apiKey: 'mnfst_full_decrypted' });
   });
 
   it('returns full apiKey when service returns fullKey', async () => {
@@ -144,18 +129,6 @@ describe('AgentsController', () => {
     expect(result).not.toHaveProperty('apiKey');
   });
 
-  it('does not return full apiKey in local mode for non-default agent', async () => {
-    mockReadLocalApiKey.mockReturnValue('mnfst_full_local_key');
-    mockConfigGet.mockImplementation((key: string, fallback?: string) =>
-      key === 'MANIFEST_MODE' ? 'local' : (fallback ?? ''),
-    );
-    const user = { id: 'u1' };
-    const result = await controller.getAgentKey(user as never, 'bot-1');
-
-    expect(result).toMatchObject({ keyPrefix: 'mnfst_test1234' });
-    expect(result).not.toHaveProperty('apiKey');
-  });
-
   it('returns empty agents array when no agents exist', async () => {
     mockGetAgentList.mockResolvedValue([]);
 
@@ -200,27 +173,6 @@ describe('AgentsController', () => {
     expect(cacheManager.del).toHaveBeenCalledWith('u1:/api/v1/agents');
   });
 
-  it('throws ForbiddenException when deleting default agent in local mode', async () => {
-    mockConfigGet.mockImplementation((key: string, fallback?: string) =>
-      key === 'MANIFEST_MODE' ? 'local' : (fallback ?? ''),
-    );
-    const user = { id: 'u1' };
-    await expect(controller.deleteAgent(user as never, 'local-agent')).rejects.toThrow(
-      ForbiddenException,
-    );
-    expect(mockDeleteAgent).not.toHaveBeenCalled();
-  });
-
-  it('allows deleting non-default agents in local mode', async () => {
-    mockConfigGet.mockImplementation((key: string, fallback?: string) =>
-      key === 'MANIFEST_MODE' ? 'local' : (fallback ?? ''),
-    );
-    const user = { id: 'u1' };
-    const result = await controller.deleteAgent(user as never, 'bot-1');
-    expect(result).toEqual({ deleted: true });
-    expect(mockDeleteAgent).toHaveBeenCalledWith('u1', 'bot-1');
-  });
-
   it('passes agent_category and agent_platform to onboardAgent', async () => {
     const mockOnboard = jest.fn().mockResolvedValue({
       tenantId: 't1',