Configuration

Configure your Twenty instance with environment variables

Configure Twenty to match your infrastructure, security requirements, and integration needs.

Configuration Overview

Twenty is configured primarily through environment variables. Configuration can be set in:

• .env file (local development)
• Docker Compose .env file
• Kubernetes ConfigMaps and Secrets
• System environment variables

Core Configuration

Server Settings

NODE_ENV · string · default: "development"

Environment mode: development or production

SERVER_URL · string · required

Public URL where Twenty is accessible (e.g., https://crm.yourcompany.com)

FRONTEND_URL · string · default: "http://localhost:3001"

Frontend application URL (for development)

PORT · number · default: "3000"

Port for the server to listen on

APP_SECRET · string · required

Secret key for encryption and JWT signing. Must be at least 32 characters.

Generate a secure APP_SECRET:

openssl rand -base64 32

Database Configuration

PostgreSQL

PG_DATABASE_URL · string · required

PostgreSQL connection string:

postgres://username:password@host:port/database

PG_SSL_ALLOW_SELF_SIGNED · boolean · default: "false"

Allow self-signed SSL certificates for PostgreSQL connections

Redis

REDIS_URL · string · required

Redis connection string:

redis://host:port

Or with authentication:

redis://:password@host:port

ClickHouse (Optional)

ANALYTICS_ENABLED · boolean · default: "false"

Enable analytics with ClickHouse

CLICKHOUSE_URL · string

ClickHouse connection string for analytics:

http://default:password@localhost:8123/twenty

Storage Configuration

Local Storage

STORAGE_TYPE · string · default: "local"

Storage backend: local or s3

STORAGE_LOCAL_PATH · string · default: ".local-storage"

Path for local file storage

S3 Storage

For production deployments, S3-compatible storage is recommended:

STORAGE_TYPE · string

Set to s3 to enable S3 storage

STORAGE_S3_REGION · string

AWS region (e.g., us-east-1, eu-west-3)

STORAGE_S3_NAME · string

S3 bucket name

STORAGE_S3_ENDPOINT · string

Custom S3 endpoint for S3-compatible services (MinIO, DigitalOcean Spaces, etc.)

AWS S3

STORAGE_TYPE=s3
STORAGE_S3_REGION=us-east-1
STORAGE_S3_NAME=twenty-uploads

Authentication Configuration

Password Authentication

AUTH_PASSWORD_ENABLED · boolean · default: "true"

Enable email/password authentication

SIGN_IN_PREFILLED · boolean · default: "false"

Prefill login credentials (development only)

Google OAuth

AUTH_GOOGLE_ENABLED · boolean · default: "false"

Enable Google OAuth sign-in

AUTH_GOOGLE_CLIENT_ID · string

Google OAuth client ID from Google Cloud Console

AUTH_GOOGLE_CLIENT_SECRET · string

Google OAuth client secret

AUTH_GOOGLE_CALLBACK_URL · string

OAuth callback URL: {SERVER_URL}/auth/google/redirect

AUTH_GOOGLE_APIS_CALLBACK_URL · string

APIs callback URL: {SERVER_URL}/auth/google-apis/get-access-token

Microsoft OAuth

AUTH_MICROSOFT_ENABLED · boolean · default: "false"

Enable Microsoft OAuth sign-in

AUTH_MICROSOFT_CLIENT_ID · string

Microsoft OAuth client ID from Azure Portal

AUTH_MICROSOFT_CLIENT_SECRET · string

Microsoft OAuth client secret

AUTH_MICROSOFT_CALLBACK_URL · string

OAuth callback URL: {SERVER_URL}/auth/microsoft/redirect

AUTH_MICROSOFT_APIS_CALLBACK_URL · string

APIs callback URL: {SERVER_URL}/auth/microsoft-apis/get-access-token

Email Configuration

Email Settings

EMAIL_DRIVER · string · default: "logger"

Email driver: smtp for production, logger for development/testing

EMAIL_FROM_ADDRESS · string

Sender email address (e.g., [e-mail])

EMAIL_FROM_NAME · string

Sender display name (e.g., John from YourCompany)

EMAIL_SYSTEM_ADDRESS · string

System email address for automated messages

SMTP Configuration

EMAIL_SMTP_HOST · string

SMTP server hostname (e.g., smtp.gmail.com)

EMAIL_SMTP_PORT · number

SMTP server port (typically 587 for TLS or 465 for SSL)

EMAIL_SMTP_USER · string

SMTP username

EMAIL_SMTP_PASSWORD · string

SMTP password or app-specific password

Gmail

EMAIL_DRIVER=smtp
EMAIL_SMTP_HOST=smtp.gmail.com
EMAIL_SMTP_PORT=465
EMAIL_SMTP_USER=[e-mail]
EMAIL_SMTP_PASSWORD=your-app-password
EMAIL_FROM_ADDRESS=[e-mail]

Email Verification

IS_EMAIL_VERIFICATION_REQUIRED · boolean · default: "false"

Require email verification for new accounts

EMAIL_VERIFICATION_TOKEN_EXPIRES_IN · string · default: "1h"

Verification token expiration time

Integration Providers

Gmail Integration

MESSAGING_PROVIDER_GMAIL_ENABLED · boolean · default: "false"

Enable Gmail message sync

CALENDAR_PROVIDER_GOOGLE_ENABLED · boolean · default: "false"

Enable Google Calendar sync

Microsoft Integration

MESSAGING_PROVIDER_MICROSOFT_ENABLED · boolean · default: "false"

Enable Outlook message sync

CALENDAR_PROVIDER_MICROSOFT_ENABLED · boolean · default: "false"

Enable Outlook Calendar sync

IMAP/SMTP/CalDAV

IS_IMAP_SMTP_CALDAV_ENABLED · boolean · default: "true"

Enable generic IMAP/SMTP/CalDAV integrations

Security Configuration

Token Expiration

ACCESS_TOKEN_EXPIRES_IN · string · default: "30m"

Access token lifetime

REFRESH_TOKEN_EXPIRES_IN · string · default: "90d"

Refresh token lifetime

LOGIN_TOKEN_EXPIRES_IN · string · default: "15m"

Login token lifetime

FILE_TOKEN_EXPIRES_IN · string · default: "1d"

File access token lifetime

PASSWORD_RESET_TOKEN_EXPIRES_IN · string · default: "5m"

Password reset token lifetime

Rate Limiting

API_RATE_LIMITING_TTL · number

Rate limit window in milliseconds

API_RATE_LIMITING_LIMIT · number

Maximum requests per window

MUTATION_MAXIMUM_AFFECTED_RECORDS · number · default: "100"

Maximum records that can be affected by a single mutation

CAPTCHA

CAPTCHA_DRIVER · string

CAPTCHA provider (e.g., recaptcha, hcaptcha)

CAPTCHA_SITE_KEY · string

CAPTCHA site key

CAPTCHA_SECRET_KEY · string

CAPTCHA secret key

SSL/TLS

SSL_KEY_PATH · string

Path to SSL private key file

SSL_CERT_PATH · string

Path to SSL certificate file

Feature Flags

Workspace Settings

IS_MULTIWORKSPACE_ENABLED · boolean · default: "false"

Enable multiple workspace support

IS_WORKSPACE_CREATION_LIMITED_TO_SERVER_ADMINS · boolean · default: "false"

Restrict workspace creation to server administrators

WORKSPACE_INACTIVE_DAYS_BEFORE_NOTIFICATION · number · default: "7"

Days of inactivity before sending warning notification

WORKSPACE_INACTIVE_DAYS_BEFORE_SOFT_DELETION · number · default: "14"

Days before soft-deleting inactive workspaces

WORKSPACE_INACTIVE_DAYS_BEFORE_DELETION · number · default: "21"

Days before permanently deleting inactive workspaces

Configuration Storage

IS_CONFIG_VARIABLES_IN_DB_ENABLED · boolean · default: "false"

Store configuration variables in database instead of environment

Billing

IS_BILLING_ENABLED · boolean · default: "false"

Enable billing and subscription features

BILLING_PLAN_REQUIRED_LINK · string

URL to redirect users when subscription is required

Serverless Configuration

CODE_INTERPRETER_TYPE · string · default: "local"

Code execution environment: local or serverless

SERVERLESS_TYPE · string · default: "local"

Serverless provider: local, aws, or azure

SERVERLESS_LOGS_ENABLED · boolean · default: "true"

Enable logging for serverless functions

Observability

Logging

LOGGER_DRIVER · string · default: "console"

Logger output: console or other drivers

LOGGER_IS_BUFFER_ENABLED · boolean · default: "true"

Buffer log messages for batch processing

LOG_LEVELS · string · default: "error,warn,log"

Comma-separated log levels to output

Error Tracking

EXCEPTION_HANDLER_DRIVER · string

Exception handler: sentry or other providers

SENTRY_DSN · string

Sentry DSN for backend error tracking

SENTRY_FRONT_DSN · string

Sentry DSN for frontend error tracking

SENTRY_ENVIRONMENT · string

Environment name in Sentry (e.g., production, staging)

Metrics

METER_DRIVER · string

Metrics driver: opentelemetry, console, or comma-separated for multiple

Support Configuration

SUPPORT_DRIVER · string

Support widget driver: front for Front chat

SUPPORT_FRONT_CHAT_ID · string

Front chat widget ID

SUPPORT_FRONT_HMAC_KEY · string

Front chat HMAC key for user verification

Security Features

HTTP Tool Safe Mode

HTTP_TOOL_SAFE_MODE_ENABLED · boolean · default: "true"

Restrict HTTP requests from workflows to prevent SSRF attacks

ALLOW_REQUESTS_TO_TWENTY_ICONS · boolean · default: "true"

Allow workflows to fetch icons from Twenty’s icon service

Chrome Extension

CHROME_EXTENSION_ID · string

Chrome extension ID for browser integration

Cloudflare Configuration

CLOUDFLARE_API_KEY · string

Cloudflare API key for CDN integration

CLOUDFLARE_ZONE_ID · string

Cloudflare zone ID

CLOUDFLARE_WEBHOOK_SECRET · string

Secret for validating Cloudflare webhooks

Migration Settings

DISABLE_DB_MIGRATIONS · boolean · default: "false"

Disable automatic database migrations on startup

DISABLE_CRON_JOBS_REGISTRATION · boolean · default: "false"

Disable automatic cron job registration (useful for worker-only containers)

Example Configurations

Development Environment

.env

NODE_ENV=development
PG_DATABASE_URL=postgres://postgres:postgres@localhost:5432/default
REDIS_URL=redis://localhost:6379
APP_SECRET=dev-secret-change-in-production
SIGN_IN_PREFILLED=true
FRONTEND_URL=http://localhost:3001
SERVER_URL=http://localhost:3000
STORAGE_TYPE=local
STORAGE_LOCAL_PATH=.local-storage
EMAIL_DRIVER=logger

Production Environment

.env

NODE_ENV=production
PG_DATABASE_URL=postgres://user:[e-mail]:5432/twenty
REDIS_URL=redis://:[e-mail]:6379
APP_SECRET=your-secure-random-string-from-openssl
SERVER_URL=https://crm.yourcompany.com

# Storage
STORAGE_TYPE=s3
STORAGE_S3_REGION=us-east-1
STORAGE_S3_NAME=twenty-production-uploads

# Email
EMAIL_DRIVER=smtp
EMAIL_SMTP_HOST=smtp.sendgrid.net
EMAIL_SMTP_PORT=587
EMAIL_SMTP_USER=apikey
EMAIL_SMTP_PASSWORD=your-sendgrid-api-key
EMAIL_FROM_ADDRESS=[e-mail]
EMAIL_FROM_NAME=YourCompany CRM

# Auth
AUTH_GOOGLE_ENABLED=true
AUTH_GOOGLE_CLIENT_ID=your-client-id
AUTH_GOOGLE_CLIENT_SECRET=your-client-secret
AUTH_GOOGLE_CALLBACK_URL=https://crm.yourcompany.com/auth/google/redirect

# Monitoring
EXCEPTION_HANDLER_DRIVER=sentry
SENTRY_DSN=https://[e-mail]/xxx
SENTRY_ENVIRONMENT=production
LOG_LEVELS=error,warn

# Security
API_RATE_LIMITING_TTL=60000
API_RATE_LIMITING_LIMIT=100

Validation

Verify your configuration:

Check Server

curl http://localhost:3000/healthz

Next Steps

Docker Compose

Deploy with Docker Compose

Kubernetes

Deploy on Kubernetes

Troubleshooting

Debug configuration issues

Authentication

Configure API authentication