Cloud SaaS Mode

chmonitor Cloud (SaaS) mode

One codebase, two products. dash.chmonitor.dev = Cloud; Docker/K8s/self-built Worker = self-hosted (OSS). The difference is runtime config behind one flag.

Paid self-host path: operators who already run ClickHouse buy a commercial license (yearly/lifetime, host count, honor system). Do not push them to Polar cloud seats. Do not add a license key to the OSS binary.

This is a project skill kept under .claude/skills/ (NOT .agents/skills/, which the build:skills registry scans for end-user AI-agent skills). Keep dev skills here so they never leak into the agent bundle.

Golden rule

Fail-closed to self-hosted. Unset/junk CHM_CLOUD_MODE / VITE_CLOUD_MODE → NOT cloud → OSS unchanged. Cloud behaviour is ADDITIVE only. Never gate a core monitoring feature behind cloud mode. (Mirrors lib/edition fail-open design.)

The flag

• Resolver: apps/dashboard/src/lib/cloud/cloud-mode.ts
  • isCloudModeClient() — build-time, React/hooks (reads VITE_CLOUD_MODE).
  • isCloudModeServer(env) — runtime CHM_CLOUD_MODE wins over build-time.
  • parseCloudMode(v) — only 'true'|'1'|'cloud' (trim/case-insensitive) → true.
• Build inline: vite.config.ts CLIENT_ENV + src/vite-env.d.ts. Each client VITE_* DERIVES from the canonical CHM_* (set the value once).
• Single source of truth: apps/dashboard/.env.production (+ .env.preview overlay). It feeds BOTH the vite client build (CHM_BUILD_ENV=production|preview → build:production/build:preview) AND the Worker runtime [vars] (apps/dashboard/scripts/patch-wrangler-env.ts injects the non-VITE_ keys). wrangler.toml declares NO [vars] — never re-add one; edit .env.production.
• Self-hosted uses the same names from apps/dashboard/.env.example (Docker env_file, Helm values.yaml). Secrets only via set-secrets.ts / K8s Secret.

Cloud mode is a BUILD-TIME contract (#2515). The client bundle only sees the baked-in VITE_CLOUD_MODE; it never reads runtime env. Booting a prebuilt OSS image with runtime CHM_DEPLOYMENT_MODE=cloud / CHM_CLOUD_MODE=true splits the product — server enforces cloud (demo guard) while the client renders OSS UI. Enable cloud by setting CHM_CLOUD_MODE before the build (so the VITE derivation runs), not only at runtime. Guard: detectCloudModeMismatch(env) → {server, clientBuild, mismatch}; /api/healthz warns and reports cloudMode on mismatch. The reverse (cloud build, runtime unset) is safe — fail-closed.

Behaviour

Resolver: lib/auth/device-login-config.ts. Store: D1 or in-memory (lib/auth/device-code-store.ts). See docs/knowledge/standalone-cli.md.

CLI auth discovery: GET /api/v1/auth/cli (public) returns method none|device|api_key for chm auth login — no auth_mode in CLI config. Code: lib/auth/cli-auth-discovery.ts.

Welcome / setup page

components/host/first-run-empty-state.tsx renders 3 variants by (cloudMode, isSignedIn): cloud signed-in (Connect-your-host + Add-host dialog), cloud anon (sign-in + value prop), self-hosted (env-var guidance + browser add). Gate ClerkSignInButton behind isClerkEnabled().

Human vs agent auth URLs (#3092). /sign-in and /sign-up are human HTML pages (components/clerk/auth-page.tsx: Clerk modal CTA, or an explicit "use the dashboard Sign in control" fallback when Clerk is off). /login redirects to /sign-in. /auth.md is the agent-facing markdown document. agentDiscoveryHandler in start.ts must never rewrite the human auth paths to text/markdown — a cached markdown HIT is what made dash.chmonitor.dev/sign-in unusable for people.

Demo down (#3592). If the active host is source:'demo' and host-status fails, FirstRunGate shows DemoUnavailableBanner ("Demo temporarily unavailable" + Retry, components/host/demo-unavailable-banner.tsx). Demo-only via isDemoUnavailable; OSS/env hosts never see it. Don't add per-card demo-down handling.

Cloud signed-in welcome: connect a host immediately. There is no Polar plan picker and no dashboard /billing page. Public paid checkout is self-host licenses on chmonitor.dev/pricing → hooks.chmonitor.dev/checkout/license. Host/seat counts are not enforced. OSS fails open.

"Try with sample ClickHouse" preset — a DIFFERENT thing from the demo host above (server env-configured, cloud-only): a one-click preset any user (OSS or cloud signed-in) can add through the NORMAL add-host path, for the "must own a cluster to try it" barrier. Not shown to cloud anon visitors (they already get the automatic demo). components/connections/sample-preset.ts is the single constant (SAMPLE_CLUSTER_PRESET + isSampleClusterHost) — currently the public ClickHouse Playground (play.clickhouse.com/explorer, non-secret, DDL/INSERT rejected server-side); that shared demo also denies several system.* tables chmonitor needs (query_log, parts, merges, processes, replicas, mutations, disks, errors), so operational pages show their normal empty/error states against it — schema browsing, metrics/settings/functions, and SQL/AI chat work. add-host-dialog.tsx's initialPreset?: 'sample' must be set explicitly (incl. undefined) on every open — the dialog is reused, not remounted per-CTA. components/host/sample-cluster-banner.tsx is the dismissible "Connect your own cluster" convert nudge shown once the sample is connected. Full detail: docs/knowledge/cloud-saas-mode.md.