Getting Started

Configuration

Environment variables, feature flags, and service toggles for local and production setups.

Environment File Strategy

Use the root .env.example as the canonical template and copy it to:

apps/app/.env
apps/admin/.env
apps/web/.env

Per-app env model

Each Next.js app reads its own .env file at runtime/build time. Keep shared values synchronized unless a value is intentionally app-specific.

Required Baseline Variables

DATABASE_URL
BETTER_AUTH_SECRET
BETTER_AUTH_URL / app URL variables
At least one AI provider key (GROQ_API_KEY or OPENAI_API_KEY)

Common Infrastructure Variables

Redis: REDIS_URL
S3/MinIO: S3_ENDPOINT, S3_ACCESS_KEY, S3_SECRET_KEY, S3_BUCKET
Search and scraping: SEARXNG_URL, BROWSER_USE_API_URL
Email (local default MailDev): SMTP_HOST, SMTP_PORT

Feature and Service Controls

Feature flags

FEATURE_SEARCH_ENABLED=true
FEATURE_DEEP_SEARCH_ENABLED=true
FEATURE_MEMORY_ENABLED=true
FEATURE_ARTIFACTS_ENABLED=true
FEATURE_TRANSCRIPTION_ENABLED=true
FEATURE_DOCUMENT_COMPARISON_ENABLED=true
FEATURE_BILLING_ENFORCEMENT_ENABLED=true
FEATURE_ANALYTICS_ENABLED=true
DEVELOPMENT_MODE=false

Service availability toggles

SERVICE_SEARXNG_AVAILABLE=true
SERVICE_BROWSERUSE_AVAILABLE=true
SERVICE_QDRANT_AVAILABLE=true
SERVICE_NEO4J_AVAILABLE=false

Optional Integrations

Stripe billing (STRIPE_*)
Google OAuth (GOOGLE_CLIENT_*)
Telegram integration (TELEGRAM_*)

If optional variables are unset, related features are unavailable but core app behavior continues.

Suggested Env Profiles

FEATURE_SEARCH_ENABLED=false
FEATURE_DEEP_SEARCH_ENABLED=false
FEATURE_MEMORY_ENABLED=false
SERVICE_SEARXNG_AVAILABLE=false
SERVICE_QDRANT_AVAILABLE=false
DEVELOPMENT_MODE=true

FEATURE_SEARCH_ENABLED=true
FEATURE_DEEP_SEARCH_ENABLED=true
FEATURE_MEMORY_ENABLED=true
DEVELOPMENT_MODE=true

FEATURE_BILLING_ENFORCEMENT_ENABLED=true
DEVELOPMENT_MODE=false

Use strong secrets, real domains, and only enable features backed by deployed services.

Production Caveats

Never keep development defaults in production (password, minioadmin, placeholder secrets).
Ensure APP_URL and auth URLs match real domains.
For Telegram webhook integration, set APP_URL and TELEGRAM_CHAT_WEBHOOK_SECRET_TOKEN, then register webhook.
For Stripe billing flows, configure webhook endpoint and required event types.

Configuration Checklist

Generated a strong BETTER_AUTH_SECRET
Set valid DB/Redis/S3 endpoints for your environment
Enabled only features backed by deployed services
Confirmed URL variables match exposed domains
Restarted apps/workers after env changes

Setup

Install, bootstrap, and run the AI Assistant monorepo locally.

Troubleshooting

High-signal fixes for common local setup, runtime, and integration failures.

On this page

Environment File Strategy Required Baseline Variables Common Infrastructure Variables Feature and Service Controls Feature flags Service availability toggles Optional Integrations Suggested Env Profiles Production Caveats Configuration Checklist