feat(self-host): add capability-aware setup

Author: TheodoreSpeaks

.github/CONTRIBUTING.md

@@ -316,7 +316,7 @@ If you prefer not to use Docker or Dev Containers. **All commands run from the r
    ```bash
    bun run type-check   # TypeScript across every workspace
    bun run lint:check   # Biome lint across every workspace
-   bun run test         # Vitest across every workspace
+   bun run test         # Setup CLI Bun tests, then Vitest across every workspace
    ```
 
 ### Email Template Development

.github/workflows/test-build.yml

@@ -159,6 +159,9 @@ jobs:
       - name: Verify generated tool metadata is in sync
         run: bun run tool-metadata:check
 
+      - name: Verify integration deployment metadata is in sync
+        run: bun run integration-catalog:check
+
       - name: Verify skill projections are in sync
         run: bun run skills:check
 
@@ -183,8 +186,8 @@ jobs:
       - name: Install ripgrep
         run: command -v rg || (sudo apt-get update && sudo apt-get install -y ripgrep)
 
-      # Named for what it does: `bun run test` is `vitest run`, with no
-      # `--coverage`. See the Codecov note below.
+      # Runs the setup CLI's Bun tests plus each workspace's Vitest suite,
+      # without `--coverage`. See the Codecov note below.
       - name: Run tests
         env:
           NODE_OPTIONS: '--no-warnings --max-old-space-size=8192'

README.md

@@ -28,6 +28,7 @@
 
 ```bash
 git clone https://github.com/simstudioai/sim.git && cd sim
+bun install
 bun run setup
 ```
 
@@ -84,6 +85,25 @@ Open [http://localhost:3000](http://localhost:3000)
 
 When it finishes, open [http://localhost:3000](http://localhost:3000).
 
+Reconfigure an optional capability without rerunning the full wizard:
+
+```bash
+bun run setup status
+bun run setup email
+bun run setup storage
+bun run setup sandbox
+bun run setup jobs
+bun run setup cache
+bun run setup knowledge
+bun run setup llm
+bun run setup integration slack
+```
+
+`bun run setup status` detects the effective local-dev, Docker Compose, or current-context
+Helm configuration and reports configured, missing, or invalid capabilities and OAuth
+integrations without printing credential values. This is separate from `bun run sim status`,
+which reports whether installed services are running and healthy.
+
 Manage your install with `bun run sim`:
 
 ```bash

apps/sim/.env.example

@@ -96,7 +96,11 @@ CRON_SECRET=your_cron_secret # Use `openssl rand -hex 32` to generate. Authentic
 # CONTEXT_DEV_API_KEY_1=                         # Context.dev API key #1
 # CONTEXT_DEV_API_KEY_2=                         # Context.dev API key #2
 
+# PDF OCR provider (Optional - defaults to local; legacy installs infer Mistral from configured credentials)
+# OCR_PROVIDER=local                              # One of: local, mistral, azure-mistral
+
 # File Storage (Optional - defaults to local disk; use S3, Azure Blob, or Google Cloud Storage for production)
+# STORAGE_PROVIDER=local                          # One of: local, s3, azure, gcs. Required when cloud storage is configured
 # AWS_REGION=us-east-1                            # Required with S3_BUCKET_NAME to enable S3. Use "auto" for Cloudflare R2
 # AWS_ACCESS_KEY_ID=                              # Omit to use the instance/IRSA credential chain
 # AWS_SECRET_ACCESS_KEY=                          # Omit to use the instance/IRSA credential chain
@@ -121,7 +125,7 @@ CRON_SECRET=your_cron_secret # Use `openssl rand -hex 32` to generate. Authentic
 # TIKTOK_CLIENT_ID=
 # TIKTOK_CLIENT_SECRET=
 
-# Azure Blob Storage takes precedence over S3 if both are configured
+# Azure Blob Storage
 # AZURE_ACCOUNT_NAME=                             # Azure storage account name
 # AZURE_ACCOUNT_KEY=                              # Azure storage account key
 # AZURE_CONNECTION_STRING=                        # Alternative to account name/key
@@ -134,7 +138,7 @@ CRON_SECRET=your_cron_secret # Use `openssl rand -hex 32` to generate. Authentic
 # AZURE_STORAGE_OG_IMAGES_CONTAINER_NAME=         # OpenGraph preview images (falls back to AZURE_STORAGE_CONTAINER_NAME)
 # AZURE_STORAGE_WORKSPACE_LOGOS_CONTAINER_NAME=   # Workspace logos (falls back to AZURE_STORAGE_CONTAINER_NAME)
 
-# Google Cloud Storage (used when neither Azure Blob nor S3 is configured)
+# Google Cloud Storage
 # GCS_PROJECT_ID=                                 # GCP project ID (optional — inferred from credentials/ADC when unset)
 # GCS_CREDENTIALS_JSON=                           # Inline service-account JSON. Omit to use Application Default Credentials (Workload Identity, GOOGLE_APPLICATION_CREDENTIALS)
 # GCS_BUCKET_NAME=                                # General workspace files bucket (enables GCS; all other buckets fall back to it)

apps/sim/app/api/auth/instagram/authorize/route.ts

@@ -5,6 +5,7 @@ import { authorizeInstagramContract } from '@/lib/api/contracts/oauth-connection
 import { parseRequest } from '@/lib/api/server'
 import { getSession } from '@/lib/auth'
 import { env } from '@/lib/core/config/env'
+import { requireConfiguredOAuthClient } from '@/lib/core/config/env-capabilities.server'
 import { getBaseUrl } from '@/lib/core/utils/urls'
 import { isSameOrigin } from '@/lib/core/utils/validation'
 import { withRouteHandler } from '@/lib/core/utils/with-route-handler'
@@ -28,6 +29,8 @@ export const GET = withRouteHandler(async (request: NextRequest) => {
       return NextResponse.json({ error: 'Unauthorized' }, { status: 401 })
     }
 
+    requireConfiguredOAuthClient('instagram')
+
     const clientId = env.INSTAGRAM_CLIENT_ID
     if (!clientId) {
       logger.error('INSTAGRAM_CLIENT_ID not configured')

apps/sim/app/api/auth/oauth2/authorize/route.test.ts

@@ -81,7 +81,11 @@ describe('OAuth2 authorize route', () => {
   beforeEach(() => {
     vi.clearAllMocks()
     resetDbChainMock()
-    setEnv({ NEXT_PUBLIC_APP_URL: BASE_URL })
+    setEnv({
+      NEXT_PUBLIC_APP_URL: BASE_URL,
+      GOOGLE_CLIENT_ID: 'google-client',
+      GOOGLE_CLIENT_SECRET: 'google-secret',
+    })
     mockGetSession.mockResolvedValue({ user: { id: USER_ID } })
     mockCheckWorkspaceAccess.mockResolvedValue({
       hasAccess: true,
@@ -139,6 +143,18 @@ describe('OAuth2 authorize route', () => {
       expect(set).toHaveProperty('credentialId', null)
     })
 
+    it('rejects an OAuth client that is not configured for the deployment', async () => {
+      setEnv({ GOOGLE_CLIENT_ID: undefined, GOOGLE_CLIENT_SECRET: undefined })
+
+      const response = await GET(
+        authorizeRequest({ providerId: 'google-email', workspaceId: WORKSPACE_ID })
+      )
+
+      expect(response.headers.get('location')).toBe(`${BASE_URL}/workspace?error=oauth_link_failed`)
+      expect(dbChainMockFns.values).not.toHaveBeenCalled()
+      expect(mockOAuth2LinkAccount).not.toHaveBeenCalled()
+    })
+
     it('redirects to login when unauthenticated', async () => {
       mockGetSession.mockResolvedValue(null)
 

apps/sim/app/api/auth/oauth2/authorize/route.ts

@@ -3,6 +3,7 @@ import { type NextRequest, NextResponse } from 'next/server'
 import { authorizeOAuth2Contract } from '@/lib/api/contracts/oauth-connections'
 import { parseRequest } from '@/lib/api/server'
 import { auth, getSession } from '@/lib/auth/auth'
+import { requireConfiguredOAuthClient } from '@/lib/core/config/env-capabilities.server'
 import { getBaseUrl } from '@/lib/core/utils/urls'
 import { withRouteHandler } from '@/lib/core/utils/with-route-handler'
 import { getCredentialActorContext } from '@/lib/credentials/access'
@@ -100,6 +101,8 @@ export const GET = withRouteHandler(async (request: NextRequest) => {
       reconnectDisplayName = actor.credential.displayName
     }
 
+    requireConfiguredOAuthClient(providerId)
+
     // Create the draft before initiating the link so it is guaranteed to exist
     // (and freshly clocked) when the OAuth callback's `account.create.after`
     // hook runs. If this throws, we never start the OAuth flow.

apps/sim/app/api/auth/shopify/authorize/route.ts

@@ -7,6 +7,7 @@ import {
 } from '@/lib/api/contracts/oauth-connections'
 import { getSession } from '@/lib/auth'
 import { env } from '@/lib/core/config/env'
+import { requireConfiguredOAuthClient } from '@/lib/core/config/env-capabilities.server'
 import { getBaseUrl } from '@/lib/core/utils/urls'
 import { isSameOrigin } from '@/lib/core/utils/validation'
 import { withRouteHandler } from '@/lib/core/utils/with-route-handler'
@@ -25,8 +26,9 @@ export const GET = withRouteHandler(async (request: NextRequest) => {
       return NextResponse.json({ error: 'Unauthorized' }, { status: 401 })
     }
 
-    const clientId = env.SHOPIFY_CLIENT_ID
+    requireConfiguredOAuthClient('shopify')
 
+    const clientId = env.SHOPIFY_CLIENT_ID
     if (!clientId) {
       logger.error('SHOPIFY_CLIENT_ID not configured')
       return NextResponse.json({ error: 'Shopify client ID not configured' }, { status: 500 })

apps/sim/app/api/settings/allowed-integrations/route.ts

@@ -2,6 +2,7 @@ import { NextResponse } from 'next/server'
 import { getSession } from '@/lib/auth'
 import { getAllowedIntegrationsFromEnv } from '@/lib/core/config/env-flags'
 import { withRouteHandler } from '@/lib/core/utils/with-route-handler'
+import { getIntegrationAvailability } from '@/lib/integrations/availability.server'
 
 export const GET = withRouteHandler(async () => {
   const session = await getSession()
@@ -11,5 +12,8 @@ export const GET = withRouteHandler(async () => {
 
   return NextResponse.json({
     allowedIntegrations: getAllowedIntegrationsFromEnv(),
+    integrationAvailability: getIntegrationAvailability().map(
+      ({ type, state, oauthAvailable }) => ({ type, state, oauthAvailable })
+    ),
   })
 })

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

@@ -13,6 +13,7 @@ import {
   resolveCredentialDisplay,
   resolveOAuthServiceForIntegration,
 } from '@/lib/integrations'
+import { getServiceAccountMetadata } from '@/lib/integrations/service-account-metadata'
 import { credentialProviderMatchesService } from '@/lib/oauth'
 import { ConnectOAuthModal } from '@/app/workspace/[workspaceId]/components/connect-oauth-modal'
 import { RESOURCE_TILE_BASE } from '@/app/workspace/[workspaceId]/components/resource-tile'
@@ -40,6 +41,7 @@ import {
 } from '@/blocks/registry'
 import { useWorkspaceCredentials } from '@/hooks/queries/credentials'
 import { useOAuthReturnRouter } from '@/hooks/use-oauth-return'
+import { usePermissionConfig } from '@/hooks/use-permission-config'
 
 /** Maximum number of overlapping icon tiles rendered per template row. */
 const TEMPLATE_CLUSTER_MAX = 3 as const
@@ -64,6 +66,9 @@ export function IntegrationBlockDetail({ integration, workspaceId }: Integration
   const matchingTemplates = getTemplatesForBlock(integration.type)
   const suggestedSkills = getSuggestedSkillsForBlock(integration.type)
   const oauthService = resolveOAuthServiceForIntegration(integration)
+  const { integrationAvailability, isLoading: permissionConfigLoading } = usePermissionConfig()
+  const availability = integrationAvailability.get(integration.type.toLowerCase())
+  const oauthAvailable = Boolean(oauthService) && (availability?.oauthAvailable ?? true)
   const [oauthOpen, setOAuthOpen] = useState(false)
 
   const { data: credentials = [], isPending: credentialsLoading } = useWorkspaceCredentials({
@@ -93,40 +98,61 @@ export function IntegrationBlockDetail({ integration, workspaceId }: Integration
     serviceName: oauthService?.serviceName,
     serviceIcon: oauthService?.serviceIcon,
   })
-  const hasServiceAccount = Boolean(serviceAccountTarget) && !serviceAccountTarget?.hidden
+  const serviceAccountMetadata = integration.oauthServiceId
+    ? getServiceAccountMetadata(integration.oauthServiceId)
+    : undefined
+  const serviceAccountDeploymentAvailable =
+    availability?.state === 'ready' ||
+    availability?.state === 'limited' ||
+    (availability?.state === 'unavailable' &&
+      serviceAccountMetadata?.deploymentRequirement === 'preview-gated')
+  const hasServiceAccount =
+    serviceAccountDeploymentAvailable &&
+    Boolean(serviceAccountTarget) &&
+    !serviceAccountTarget?.hidden
   const serviceAccountConnectLabel = serviceAccountTarget?.label ?? 'Add service account'
   const hasHandledConnectQueryRef = useRef(false)
 
   useEffect(() => {
-    if (hasHandledConnectQueryRef.current) return
-    if (!connectMode) return
+    if (hasHandledConnectQueryRef.current || !connectMode || permissionConfigLoading) return
 
-    let handled = false
-    if (connectMode === CONNECT_MODE.oauth && oauthService) {
+    if (connectMode === CONNECT_MODE.oauth && oauthService && oauthAvailable) {
       setOAuthOpen(true)
-      handled = true
     } else if (connectMode === CONNECT_MODE.serviceAccount && hasServiceAccount) {
       setServiceAccountOpen(true)
-      handled = true
     }
-    if (!handled) return
 
     hasHandledConnectQueryRef.current = true
     void setConnectMode(null, { history: 'replace', scroll: false })
-  }, [connectMode, oauthService, hasServiceAccount, setConnectMode])
+  }, [
+    connectMode,
+    oauthService,
+    oauthAvailable,
+    hasServiceAccount,
+    permissionConfigLoading,
+    setConnectMode,
+  ])
 
   const connectOptions = oauthService
     ? [
-        {
-          value: CONNECT_MODE.oauth,
-          label: 'Connect with OAuth',
-          icon: oauthService.serviceIcon,
-        },
-        {
-          value: CONNECT_MODE.serviceAccount,
-          label: serviceAccountConnectLabel,
-          icon: serviceAccountTarget?.serviceIcon ?? oauthService.serviceIcon,
-        },
+        ...(oauthAvailable
+          ? [
+              {
+                value: CONNECT_MODE.oauth,
+                label: 'Connect with OAuth',
+                icon: oauthService.serviceIcon,
+              },
+            ]
+          : []),
+        ...(hasServiceAccount
+          ? [
+              {
+                value: CONNECT_MODE.serviceAccount,
+                label: serviceAccountConnectLabel,
+                icon: serviceAccountTarget?.serviceIcon ?? oauthService.serviceIcon,
+              },
+            ]
+          : []),
       ]
     : []
 
@@ -148,7 +174,7 @@ export function IntegrationBlockDetail({ integration, workspaceId }: Integration
         </ChipLink>
         <div className={cn('ml-auto', HEADER_ACTION_CLUSTER)}>
           {oauthService ? (
-            hasServiceAccount ? (
+            connectOptions.length > 1 ? (
               <ChipDropdown
                 variant='primary'
                 leftIcon={Plus}
@@ -158,10 +184,16 @@ export function IntegrationBlockDetail({ integration, workspaceId }: Integration
                 onChange={handleSelectConnectOption}
                 matchTriggerWidth={false}
               />
-            ) : (
+            ) : oauthAvailable ? (
               <Chip variant='primary' leftIcon={Plus} onClick={() => setOAuthOpen(true)}>
                 Add to Sim
               </Chip>
+            ) : hasServiceAccount ? (
+              <Chip variant='primary' leftIcon={Plus} onClick={() => setServiceAccountOpen(true)}>
+                {serviceAccountConnectLabel}
+              </Chip>
+            ) : (
+              <Chip disabled>Unavailable</Chip>
             )
           ) : isChatEnabled ? (
             <Chip variant='primary' leftIcon={Plus} onClick={handleAddInChat}>
@@ -170,7 +202,7 @@ export function IntegrationBlockDetail({ integration, workspaceId }: Integration
           ) : null}
         </div>
       </div>
-      {oauthService && (
+      {oauthService && oauthAvailable && (
         <ConnectOAuthModal
           mode='connect'
           origin='integrations'