feat(chat): hide the Chat module when CHAT_ENABLED is unset

A self-hosted deployment that skipped the chat key still rendered the full
mothership Chat UI, landing on the composer and 401ing on every message.

Gate it behind a CHAT_ENABLED / NEXT_PUBLIC_CHAT_ENABLED twin, written by the
setup wizard alongside COPILOT_API_KEY and validated by the existing FLAG_TWINS
doctor check. The flag resolves at module scope on both render passes, so no
chat surface renders then disappears.

With Chat off the workspace lands on its first workflow (resolved server-side,
behind the cached host-context check so no workflow id leaks to non-members),
and the chats list, scheduled tasks, editor Chat panel, and chat CTAs are
absent. Routes are gated rather than deleted: /home redirects because it is
baked into delivered invitation emails and the accept contract.

Also fixes two bugs the gate exposed: a persisted activeTab of 'copilot' left
the workflow panel blank from first paint, and the panel's handoff listener
claimed MOTHERSHIP_SEND_MESSAGE events outside its own gate, silently
swallowing "Fix in Chat" messages.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_012ErcRgvi7VQBeKDQ3MBMha

Author: TheodoreSpeaks

apps/docs/content/docs/en/platform/self-hosting/environment-variables.mdx

@@ -64,7 +64,9 @@ import { Callout } from 'fumadocs-ui/components/callout'
 | Variable | Description |
 |----------|-------------|
 | `API_ENCRYPTION_KEY` | Encrypts stored API keys (32 hex chars): `openssl rand -hex 32` |
-| `COPILOT_API_KEY` | API key for copilot features |
+| `COPILOT_API_KEY` | API key for Chat. Required whenever `CHAT_ENABLED` is set — the app refuses to start without it |
+| `CHAT_ENABLED` | Shows the Chat module. Leave unset and the workspace lands on your first workflow, with no chats list, scheduled tasks, editor Chat panel, or Sim Chat block |
+| `NEXT_PUBLIC_CHAT_ENABLED` | Browser twin of `CHAT_ENABLED`. Set both together (`bun run setup` does) |
 | `ADMIN_API_KEY` | Admin API key for GitOps operations |
 | `ALLOWED_LOGIN_DOMAINS` | Restrict signups to domains (comma-separated) |
 | `ALLOWED_LOGIN_EMAILS` | Restrict signups to specific emails (comma-separated) |

apps/sim/.env.example

@@ -21,6 +21,15 @@ NEXT_PUBLIC_APP_URL=http://localhost:3000
 # TRUSTED_ORIGINS=https://www.example.com,https://app.example.com  # Optional: comma-separated additional public origins to trust for auth (apex+www, alias domains). Merged into Better Auth trustedOrigins.
 # AUTH_TRUSTED_PROXIES=10.0.0.0/24,192.0.2.10  # Optional: reverse-proxy IPs/CIDRs in front of the app. Better Auth walks x-forwarded-for right to left, skips these hops, and uses the first untrusted address as the client IP (prevents forwarded-header spoofing). Use your proxies' actual addresses, not broad private ranges that also cover clients.
 
+# Chat (Optional)
+# Leave these unset and the Chat module is hidden entirely: the workspace lands
+# on your first workflow, and the chats list, scheduled tasks, workflow-editor
+# Chat panel, and Sim Chat block are all absent. `bun run setup` writes all three
+# together; set them by hand only if you skip the wizard.
+# COPILOT_API_KEY=                      # Mint one at https://sim.ai — required whenever CHAT_ENABLED is true (the app refuses to boot otherwise)
+# CHAT_ENABLED=true                     # Server-side gate
+# NEXT_PUBLIC_CHAT_ENABLED=true         # Browser twin — must match CHAT_ENABLED
+
 # Security (Required)
 ENCRYPTION_KEY=your_encryption_key  # Use `openssl rand -hex 32` to generate, used to encrypt environment variables
 INTERNAL_API_SECRET=your_internal_api_secret # Use `openssl rand -hex 32` to generate, used to encrypt internal api routes

apps/sim/app/api/mothership/events/route.ts

@@ -11,6 +11,7 @@ import type { NextRequest } from 'next/server'
 import { mothershipEventsQuerySchema } from '@/lib/api/contracts/mothership-chats'
 import { validationErrorResponse } from '@/lib/api/server'
 import { chatPubSub } from '@/lib/copilot/chat-status'
+import { isChatEnabled } from '@/lib/core/config/env-flags'
 import { withRouteHandler } from '@/lib/core/utils/with-route-handler'
 import { createWorkspaceSSE } from '@/lib/events/sse-endpoint'
 
@@ -37,6 +38,10 @@ const mothershipEventsHandler = createWorkspaceSSE({
 })
 
 export const GET = withRouteHandler((request: NextRequest) => {
+  // Closes streams held by tabs that were open when Chat was turned off; the
+  // client hook already declines to open new ones.
+  if (!isChatEnabled) return new Response(null, { status: 404 })
+
   const validation = mothershipEventsQuerySchema.safeParse(
     Object.fromEntries(request.nextUrl.searchParams.entries())
   )

apps/sim/app/api/schedules/execute/route.ts

@@ -17,6 +17,7 @@ import {
 } from '@/lib/billing/core/billing-attribution'
 import { getJobQueue, shouldExecuteInline } from '@/lib/core/async-jobs'
 import { JOB_STATUS, type Job } from '@/lib/core/async-jobs/types'
+import { env } from '@/lib/core/config/env'
 import { isRetryableInfrastructureError } from '@/lib/core/errors/retryable-infrastructure'
 import { getMaxExecutionTimeout } from '@/lib/core/execution-limits'
 import { runDetached } from '@/lib/core/utils/background'
@@ -1212,7 +1213,18 @@ export async function runScheduleTick(requestId: string): Promise<ScheduleTickRe
   let iterations = 0
   let remainingWorkflowBudget = SCHEDULE_WORKFLOW_ENQUEUE_LIMIT
   let schedulesExhausted = false
-  let jobsExhausted = false
+  /**
+   * Prompt jobs run through the mothership, so without a key every claim ends in
+   * a 401. Skipping the claim entirely leaves the rows `active` and resumable;
+   * claiming them would burn each one through `MAX_CONSECUTIVE_FAILURES` and
+   * permanently disable a schedule the user can no longer see, let alone stop.
+   * Keyed on the credential rather than `CHAT_ENABLED` so jobs keep running for
+   * a deployment that only hid the UI.
+   */
+  let jobsExhausted = !env.COPILOT_API_KEY
+  if (jobsExhausted) {
+    logger.info(`[${requestId}] COPILOT_API_KEY not set, skipping prompt job claims`)
+  }
 
   while (Date.now() - tickStart < MAX_TICK_DURATION_MS) {
     if (schedulesExhausted && jobsExhausted) break

apps/sim/app/layout.tsx

@@ -6,7 +6,12 @@ import { BrandedLayout } from '@/components/branded-layout'
 import { PostHogProvider } from '@/app/_shell/providers/posthog-provider'
 import { generateBrandedMetadata, generateThemeCSS } from '@/ee/whitelabeling'
 import '@/app/_styles/globals.css'
-import { isHosted, isReactGrabEnabled, isReactScanEnabled } from '@/lib/core/config/env-flags'
+import {
+  isChatEnabled,
+  isHosted,
+  isReactGrabEnabled,
+  isReactScanEnabled,
+} from '@/lib/core/config/env-flags'
 import { HydrationErrorHandler } from '@/app/_shell/hydration-error-handler'
 import { QueryProvider } from '@/app/_shell/providers/query-provider'
 import { SessionProvider } from '@/app/_shell/providers/session-provider'
@@ -131,6 +136,12 @@ export default function RootLayout({ children }: { children: React.ReactNode })
                     }
 
                     var activeTab = panelState && panelState.activeTab;
+                    // A session that used the Chat tab before it was turned off still
+                    // has 'copilot' persisted; without this the CSS hides every tab
+                    // body and the panel paints empty.
+                    if (activeTab === 'copilot' && !${isChatEnabled}) {
+                      activeTab = 'toolbar';
+                    }
                     if (activeTab) {
                       document.documentElement.setAttribute('data-panel-active-tab', activeTab);
                     }

apps/sim/app/workspace/[workspaceId]/chat/[chatId]/layout.tsx

@@ -1,3 +1,8 @@
+import { notFound } from 'next/navigation'
+import { isChatEnabled } from '@/lib/core/config/env-flags'
+
 export default function ChatLayout({ children }: { children: React.ReactNode }) {
+  if (!isChatEnabled) notFound()
+
   return <div className='flex h-full flex-1 flex-col overflow-hidden'>{children}</div>
 }

apps/sim/app/workspace/[workspaceId]/home/layout.tsx

@@ -1,6 +1,25 @@
+import { redirect } from 'next/navigation'
+import { isChatEnabled } from '@/lib/core/config/env-flags'
 import { inter } from '@/app/_styles/fonts/inter/inter'
 
-export default function HomeLayout({ children }: { children: React.ReactNode }) {
+/**
+ * Redirects rather than 404s when Chat is disabled: this path is baked into
+ * already-delivered invitation emails and into the invitation-accept API
+ * contract, so it has to keep resolving. `/workspace/{id}` re-resolves the
+ * landing route server-side, so the visitor lands on a workflow instead.
+ */
+export default async function HomeLayout({
+  children,
+  params,
+}: {
+  children: React.ReactNode
+  params: Promise<{ workspaceId: string }>
+}) {
+  if (!isChatEnabled) {
+    const { workspaceId } = await params
+    redirect(`/workspace/${workspaceId}`)
+  }
+
   return (
     <div className={`flex h-full flex-1 flex-col overflow-hidden ${inter.variable}`}>
       {children}

apps/sim/app/workspace/[workspaceId]/home/page.tsx

@@ -1,7 +1,9 @@
 import { Suspense } from 'react'
 import { dehydrate, HydrationBoundary } from '@tanstack/react-query'
 import type { Metadata } from 'next'
+import { redirect } from 'next/navigation'
 import { getSession } from '@/lib/auth'
+import { isChatEnabled } from '@/lib/core/config/env-flags'
 import { getQueryClient } from '@/app/_shell/providers/get-query-client'
 import { prefetchHomeLists } from '@/app/workspace/[workspaceId]/home/prefetch'
 import { Home } from './home'
@@ -14,6 +16,12 @@ export const metadata: Metadata = {
 export default async function HomePage({ params }: { params: Promise<{ workspaceId: string }> }) {
   const { workspaceId } = await params
 
+  // The layout redirects too, but pages and layouts resolve concurrently — without
+  // this the prefetch below still fires on its way out.
+  if (!isChatEnabled) {
+    redirect(`/workspace/${workspaceId}`)
+  }
+
   const queryClient = getQueryClient()
   const listsPrefetch = prefetchHomeLists(queryClient, workspaceId)
 

apps/sim/app/workspace/[workspaceId]/integrations/[block]/integration-block-detail.tsx

@@ -6,6 +6,7 @@ import { ArrowLeft, ArrowRight, Plus } from 'lucide-react'
 import Link from 'next/link'
 import { useRouter } from 'next/navigation'
 import { useQueryState } from 'nuqs'
+import { isChatEnabled } from '@/lib/core/config/env-flags'
 import {
   blockTypeToIconMap,
   type Integration,
@@ -150,11 +151,11 @@ export function IntegrationBlockDetail({ integration, workspaceId }: Integration
                 Add to Sim
               </Chip>
             )
-          ) : (
+          ) : isChatEnabled ? (
             <Chip variant='primary' leftIcon={Plus} onClick={handleAddInChat}>
               Add to Sim
             </Chip>
-          )}
+          ) : null}
         </div>
       </div>
       {oauthService && (
@@ -236,7 +237,9 @@ export function IntegrationBlockDetail({ integration, workspaceId }: Integration
             />
           )}
 
-          {matchingTemplates.length > 0 && (
+          {/* Every template hands its prompt to Chat, so the section has no
+              destination without it. */}
+          {isChatEnabled && matchingTemplates.length > 0 && (
             <TemplatesSection
               integration={integration}
               templates={matchingTemplates}

apps/sim/app/workspace/[workspaceId]/integrations/components/showcase-with-explore/showcase-with-explore.tsx

@@ -3,6 +3,7 @@
 import { Chip } from '@sim/emcn'
 import { ArrowRight } from 'lucide-react'
 import { useParams, useRouter } from 'next/navigation'
+import { isChatEnabled } from '@/lib/core/config/env-flags'
 import { IntegrationsShowcase } from '@/app/workspace/[workspaceId]/integrations/components/integrations-showcase'
 import { storeCuratedPrompt } from '@/blocks/integration-matcher'
 
@@ -29,17 +30,19 @@ export function ShowcaseWithExplore({ prompt }: ShowcaseWithExploreProps) {
   return (
     <div className='relative'>
       <IntegrationsShowcase />
-      <Chip
-        active
-        rightIcon={ArrowRight}
-        onClick={() => {
-          storeCuratedPrompt(prompt)
-          router.push(`/workspace/${workspaceId}/home`)
-        }}
-        className='absolute right-0 bottom-0 mx-0'
-      >
-        Explore in chat
-      </Chip>
+      {isChatEnabled && (
+        <Chip
+          active
+          rightIcon={ArrowRight}
+          onClick={() => {
+            storeCuratedPrompt(prompt)
+            router.push(`/workspace/${workspaceId}/home`)
+          }}
+          className='absolute right-0 bottom-0 mx-0'
+        >
+          Explore in chat
+        </Chip>
+      )}
     </div>
   )
 }