Environment Variables

Complete reference for all environment variables used by ChatJS

This page lists every environment variable recognized by ChatJS, grouped by category. The schema is defined in apps/chat/lib/env-schema.ts and validated at build time by apps/chat/scripts/check-env.ts.

Required

These two variables must always be set. Without them the app will not start.

In addition to the two variables above, at least one AI gateway credential and at least one OAuth provider must be configured. See the sections below.

Authentication

Enable providers in chat.config.ts under authentication. At least one must be enabled. The build validator checks that every enabled provider has its corresponding env vars set.

authentication: {
  google: false, // Requires AUTH_GOOGLE_ID + AUTH_GOOGLE_SECRET
  github: true,  // Requires AUTH_GITHUB_ID + AUTH_GITHUB_SECRET
  vercel: false, // Requires VERCEL_APP_CLIENT_ID + VERCEL_APP_CLIENT_SECRET
},

GitHub OAuth

Setup: Go to GitHub Developer Settings → New OAuth App. Set the callback URL to https://yourdomain.com/api/auth/callback/github.

Google OAuth

Setup: Go to Google Cloud Console → Create credentials → OAuth 2.0 Client ID (Web application). Add https://yourdomain.com/api/auth/callback/google as an authorized redirect URI.

Vercel OAuth

Setup: Follow the Sign In with Vercel guide to create an integration.

AI Gateways

Exactly one gateway must be active. Set ai.gateway in chat.config.ts to select it.

ai: {
  gateway: "vercel", // "vercel" | "openrouter" | "openai" | "openai-compatible" | "litellm"
}

Vercel AI Gateway (default)

Provides access to 120+ models from OpenAI, Anthropic, Google, xAI, Meta, and more through a single key. This is the default gateway.

Setup: Go to Vercel AI Gateway and create an API key.

OpenRouter

Provides access to hundreds of models with per-token pricing.

Setup: Create an account at OpenRouter, then go to API Keys.

OpenAI

Direct connection to the OpenAI API. Use when you only need OpenAI models.

Setup: Follow the OpenAI quickstart to create an API key.

OpenAI Compatible

Works with any endpoint that follows the OpenAI API format: Ollama, LM Studio, vLLM, Azure OpenAI, and others.

Setup: Start your compatible server (for example, run ollama serve for Ollama), set OPENAI_COMPATIBLE_BASE_URL to its /v1 endpoint, and provide OPENAI_COMPATIBLE_API_KEY.

LiteLLM

Routes requests through a LiteLLM proxy for centralized model access, key management, routing, and spend tracking.

Setup: Start your LiteLLM proxy, set LITELLM_BASE_URL to the proxy root URL without /v1, and provide LITELLM_API_KEY only when the proxy requires auth.

Features

Tool flags live under ai.tools in chat.config.ts. File attachments remain under features.attachments. Each enabled capability has an associated environment variable requirement validated at build time.

Web Search

Enable real-time web search with citations. Requires at least one search provider key.

ai: {
  tools: {
    webSearch: { enabled: true },    // Requires TAVILY_API_KEY or FIRECRAWL_API_KEY
    urlRetrieval: { enabled: true }, // Requires FIRECRAWL_API_KEY
  },
}

MCP Connectors

Enable Model Context Protocol server connections to expose custom tools and data sources to the AI.

ai: {
  tools: {
    mcp: { enabled: true }, // Requires MCP_ENCRYPTION_KEY
  },
}

Generate a key:

openssl rand -base64 32

File Storage

Attachments, image generation, and video generation require a durable Files SDK provider. Storage requirements are generated from the selected provider and validated by scripts/check-env.ts.

features: {
  attachments: true,
},
ai: {
  tools: {
    image: { enabled: true },
    video: { enabled: true },
  },
}

Provider credentials belong in environment variables or the provider SDK’s credential chain. Non-secret adapter options belong in lib/storage-provider.ts. See File storage and the Files SDK provider reference for the requirements of your selected provider.

Code Execution Sandbox

Enable secure Python and JavaScript execution using Vercel Sandbox.

ai: {
  tools: {
    codeExecution: { enabled: true },
  },
}

Optional / Advanced

Resumable Streams

Allows users to reconnect to an ongoing AI generation after a page refresh or network interruption.

Without REDIS_URL, streams work normally but cannot be resumed after disconnection.

Cron Job Secret

Secures the /api/cron/cleanup endpoint that removes orphaned managed files.

Generate a secret:

openssl rand -base64 32

On Vercel, the platform automatically sends CRON_SECRET as a Authorization: Bearer <secret> header when triggering cron jobs.

App URL

Observability (Langfuse)

ChatJS uses OpenTelemetry via @vercel/otel and exports traces to Langfuse for LLM observability. These variables are read by the langfuse-vercel exporter and are not part of the Zod env schema. The Langfuse SDK picks them up automatically from the environment.

Omitting these variables disables trace export. The app runs normally without them.

Quick Reference

All variables in one place:

Related

• Config Reference: feature flags and gateway settings in chat.config.ts
• Deploy to Vercel: how Vercel auto-sets several of these variables
• Gateways Overview: choosing and configuring an AI gateway
• Authentication: OAuth provider setup details
• File storage: provider configuration and credentials