Configuration - Twenty

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.)

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

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., [email protected])

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

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

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

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:[email protected]:5432/twenty
REDIS_URL=redis://:[email protected]: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=[email protected]
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://[email protected]/xxx
SENTRY_ENVIRONMENT=production
LOG_LEVELS=error,warn

# Security
API_RATE_LIMITING_TTL=60000
API_RATE_LIMITING_LIMIT=100

Validation

Verify your configuration:

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

Getting Started

Self-Hosting

Extending Twenty

API Reference

Contributing

​Configuration Overview

​Core Configuration

​Server Settings

​Database Configuration

​PostgreSQL

​Redis

​ClickHouse (Optional)

​Storage Configuration

​Local Storage

​S3 Storage

​Authentication Configuration

​Password Authentication

​Google OAuth

​Microsoft OAuth

​Email Configuration

​Email Settings

​SMTP Configuration

​Email Verification

​Integration Providers

​Gmail Integration

​Microsoft Integration

​IMAP/SMTP/CalDAV

​Security Configuration

​Token Expiration

​Rate Limiting

​CAPTCHA

​SSL/TLS

​Feature Flags

​Workspace Settings

​Configuration Storage

​Billing

​Serverless Configuration

​Observability

​Logging

​Error Tracking

​Metrics

​Support Configuration

​Security Features

​HTTP Tool Safe Mode

​Chrome Extension

​Cloudflare Configuration

​Migration Settings

​Example Configurations

​Development Environment

​Production Environment

​Validation

​Next Steps

Docker Compose

Kubernetes

Troubleshooting

Authentication

Build docs developers (and LLMs) love

Configuration Overview

Core Configuration

Server Settings

Database Configuration

PostgreSQL

Redis

ClickHouse (Optional)

Storage Configuration

Local Storage

S3 Storage

Authentication Configuration

Password Authentication

Google OAuth

Microsoft OAuth

Email Configuration

Email Settings

SMTP Configuration

Email Verification

Integration Providers

Gmail Integration

Microsoft Integration

IMAP/SMTP/CalDAV

Security Configuration

Token Expiration

Rate Limiting

CAPTCHA

SSL/TLS

Feature Flags

Workspace Settings

Configuration Storage

Billing

Serverless Configuration

Observability

Logging

Error Tracking

Metrics

Support Configuration

Security Features

HTTP Tool Safe Mode

Chrome Extension

Cloudflare Configuration

Migration Settings

Example Configurations

Development Environment

Production Environment

Validation

Next Steps