twenty/packages/twenty-docs/developers/self-host/capabilities/setup.mdx

---
title: Setup
icon: "gear"
---

# Configuration Management

<Warning>
**First time installing?** Follow the [Docker Compose installation guide](/developers/self-host/capabilities/docker-compose) to get Twenty running, then return here for configuration.
</Warning>

Twenty offers **two configuration modes** to suit different deployment needs:

**Admin panel access:** Only users with admin privileges (`canAccessFullAdminPanel: true`) can access the configuration interface.

## 1. Admin Panel Configuration (Default)

```bash
IS_CONFIG_VARIABLES_IN_DB_ENABLED=true  # default
```

**Most configuration happens through the UI** after installation:

1. Access your Twenty instance (usually `http://localhost:3000`)
2. Go to **Settings / Admin Panel / Configuration Variables**
3. Configure integrations, email, storage, and more
4. Changes take effect immediately (within 15 seconds for multi-container deployments)

<Warning>
**Multi-Container Deployments:** When using database configuration (`IS_CONFIG_VARIABLES_IN_DB_ENABLED=true`), both server and worker containers read from the same database. Admin panel changes affect both automatically, eliminating the need to duplicate environment variables between containers (except for infrastructure variables).
</Warning>

**What you can configure through the admin panel:**
- **Authentication** - Google/Microsoft OAuth, password settings
- **Email** - SMTP settings, templates, verification
- **Storage** - S3 configuration, local storage paths
- **Integrations** - Gmail, Google Calendar, Microsoft services
- **Workflow & Rate Limiting** - Execution limits, API throttling
- **And much more...**

![Admin Panel Configuration Variables](/images/user-guide/setup/admin-panel-config-variables.png)

<Warning>
Each variable is documented with descriptions in your admin panel at **Settings → Admin Panel → Configuration Variables**.
Some infrastructure settings like database connections (`PG_DATABASE_URL`), server URLs (`SERVER_URL`), and secrets (`ENCRYPTION_KEY`, `FALLBACK_ENCRYPTION_KEY`) can only be configured via `.env` file.

[Complete technical reference →](https://github.com/twentyhq/twenty/blob/main/packages/twenty-server/src/engine/core-modules/twenty-config/config-variables.ts)
</Warning>

## Encryption keys

Twenty uses two env-only encryption keys:

| Variable | Purpose | Required |
| --- | --- | --- |
| `ENCRYPTION_KEY` | Primary key used to encrypt secrets at rest (OAuth tokens, application variables, signing-key private keys, TOTP secrets, sensitive config values). | Yes for new installs (legacy installs may instead rely on `APP_SECRET` — see below) |
| `FALLBACK_ENCRYPTION_KEY` | Verification-only key. Set during a rotation to the *previous* `ENCRYPTION_KEY` so existing rows remain decryptable. | Only during rotation |

For backward compatibility, if `ENCRYPTION_KEY` is unset, Twenty falls back to `APP_SECRET` for at-rest encryption — matching the legacy behaviour for older deployments. New installs should always set a dedicated `ENCRYPTION_KEY`.

Generate values with `openssl rand -base64 32` and store them somewhere safe (a secrets manager, sealed config, etc.). Losing `ENCRYPTION_KEY` means losing access to every secret stored in the database.

To rotate `ENCRYPTION_KEY` without downtime, see the [Key rotation guide](/developers/self-host/capabilities/key-rotation).

## 2. Environment-Only Configuration

```bash
IS_CONFIG_VARIABLES_IN_DB_ENABLED=false
```

**All configuration managed through `.env` files:**

1. Set `IS_CONFIG_VARIABLES_IN_DB_ENABLED=false` in your `.env` file
2. Add all configuration variables to your `.env` file
3. Restart containers for changes to take effect
4. Admin panel will show current values but cannot modify them

## Multi-Workspace Mode

By default, Twenty runs in **single-workspace mode** — ideal for most self-hosted deployments where you need one CRM instance for your organization.

### Single-Workspace Mode (Default)

```bash
IS_MULTIWORKSPACE_ENABLED=false  # default
```

- One workspace per Twenty instance
- First user automatically becomes admin with full privileges (`canImpersonate` and `canAccessFullAdminPanel`)
- New signups are disabled after the first workspace is created
- Simple URL structure: `https://your-domain.com`

### Enabling Multi-Workspace Mode

```bash
IS_MULTIWORKSPACE_ENABLED=true
DEFAULT_SUBDOMAIN=app  # default value
```

Enable multi-workspace mode for SaaS-like deployments where multiple independent teams need their own workspaces on the same Twenty instance.

**Key differences from single-workspace mode:**
- Multiple workspaces can be created on the same instance
- Each workspace gets its own subdomain (e.g., `sales.your-domain.com`, `marketing.your-domain.com`)
- Users sign up and log in at `{DEFAULT_SUBDOMAIN}.your-domain.com` (e.g., `app.your-domain.com`)
- No automatic admin privileges — first user in each workspace is a regular user
- Workspace-specific settings like subdomain and custom domain become available in workspace settings

<Warning>
**Environment-only setting:** `IS_MULTIWORKSPACE_ENABLED` can only be configured via `.env` file and requires a restart. It cannot be changed through the admin panel.
</Warning>

### DNS Configuration for Multi-Workspace

When using multi-workspace mode, configure your DNS with a wildcard record to allow dynamic subdomain creation:

```
*.your-domain.com -> your-server-ip
```

This enables automatic subdomain routing for new workspaces without manual DNS configuration.

### Restricting Workspace Creation

In multi-workspace mode, you may want to limit who can create new workspaces:

```bash
IS_WORKSPACE_CREATION_LIMITED_TO_SERVER_ADMINS=true
```

When enabled, only users with `canAccessFullAdminPanel` can create additional workspaces. Users can still create their first workspace during initial signup.

## Gmail & Google Calendar Integration

### Create Google Cloud Project

1. Go to [Google Cloud Console](https://console.cloud.google.com/)
2. Create a new project or select existing one
3. Enable these APIs:
- [Gmail API](https://console.cloud.google.com/apis/library/gmail.googleapis.com)
- [Google Calendar API](https://console.cloud.google.com/apis/library/calendar-json.googleapis.com)
- [People API](https://console.cloud.google.com/apis/library/people.googleapis.com)

### Configure OAuth

1. Go to [Credentials](https://console.cloud.google.com/apis/credentials)
2. Create OAuth 2.0 Client ID
3. Add these redirect URIs:
   - `https://{your-domain}/auth/google/redirect` (for SSO)
   - `https://{your-domain}/auth/google-apis/get-access-token` (for integrations)

### Configure in Twenty

1. Go to **Settings → Admin Panel → Configuration Variables**
2. Find the **Google Auth** section
3. Set these variables:
   - `MESSAGING_PROVIDER_GMAIL_ENABLED=true`
   - `CALENDAR_PROVIDER_GOOGLE_ENABLED=true`
   - `AUTH_GOOGLE_CLIENT_ID={client-id}`
   - `AUTH_GOOGLE_CLIENT_SECRET={client-secret}`
   - `AUTH_GOOGLE_CALLBACK_URL=https://{your-domain}/auth/google/redirect`
   - `AUTH_GOOGLE_APIS_CALLBACK_URL=https://{your-domain}/auth/google-apis/get-access-token`

<Warning>
**Environment-only mode:** If you set `IS_CONFIG_VARIABLES_IN_DB_ENABLED=false`, add these variables to your `.env` file instead.
</Warning>

**Required scopes** (automatically configured):
[See relevant source code](https://github.com/twentyhq/twenty/blob/main/packages/twenty-server/src/engine/core-modules/auth/utils/get-google-apis-oauth-scopes.ts#L4-L10)
- `https://www.googleapis.com/auth/calendar.events`
- `https://www.googleapis.com/auth/gmail.readonly`
- `https://www.googleapis.com/auth/profile.emails.read`

### If your app is in test mode

If your app is in test mode, you will need to add test users to your project.

Under [OAuth consent screen](https://console.cloud.google.com/apis/credentials/consent), add your test users to the "Test users" section.

## Microsoft 365 Integration

<Warning>
Users must have a [Microsoft 365 Licence](https://admin.microsoft.com/Adminportal/Home) to be able to use the Calendar and Messaging API. They will not be able to sync their account on Twenty without one.
</Warning>

### Create a project in Microsoft Azure

You will need to create a project in [Microsoft Azure](https://portal.azure.com/#view/Microsoft_AAD_IAM/AppGalleryBladeV2) and get the credentials.

### Enable APIs

On Microsoft Azure Console enable the following APIs in "Permissions":

- Microsoft Graph: Mail.ReadWrite
- Microsoft Graph: Mail.Send
- Microsoft Graph: Calendars.Read
- Microsoft Graph: User.Read
- Microsoft Graph: openid
- Microsoft Graph: email
- Microsoft Graph: profile
- Microsoft Graph: offline_access

Note: "Mail.ReadWrite" and "Mail.Send" are only mandatory if you want to send emails using our workflow actions. You can use "Mail.Read" instead if you only want to receive emails.

### Authorized redirect URIs

You need to add the following redirect URIs to your project:
- `https://{your-domain}/auth/microsoft/redirect` if you want to use Microsoft SSO
- `https://{your-domain}/auth/microsoft-apis/get-access-token`

### Configure in Twenty

1. Go to **Settings → Admin Panel → Configuration Variables**
2. Find the **Microsoft Auth** section
3. Set these variables:
   - `MESSAGING_PROVIDER_MICROSOFT_ENABLED=true`
   - `CALENDAR_PROVIDER_MICROSOFT_ENABLED=true`
   - `AUTH_MICROSOFT_ENABLED=true`
   - `AUTH_MICROSOFT_CLIENT_ID={client-id}`
   - `AUTH_MICROSOFT_CLIENT_SECRET={client-secret}`
   - `AUTH_MICROSOFT_CALLBACK_URL=https://{your-domain}/auth/microsoft/redirect`
   - `AUTH_MICROSOFT_APIS_CALLBACK_URL=https://{your-domain}/auth/microsoft-apis/get-access-token`

<Warning>
**Environment-only mode:** If you set `IS_CONFIG_VARIABLES_IN_DB_ENABLED=false`, add these variables to your `.env` file instead.
</Warning>

### Configure scopes
[See relevant source code](https://github.com/twentyhq/twenty/blob/main/packages/twenty-server/src/engine/core-modules/auth/utils/get-microsoft-apis-oauth-scopes.ts#L2-L9)
- 'openid'
- 'email'
- 'profile'
- 'offline_access'
- 'Mail.ReadWrite'
- 'Mail.Send'
- 'Calendars.Read'

### If your app is in test mode

If your app is in test mode, you will need to add test users to your project.

Add your test users to the "Users and groups" section.

## Background Jobs for Calendar & Messaging

After configuring Gmail, Google Calendar, or Microsoft 365 integrations, you need to start the background jobs that sync data.

Register the following recurring jobs in your worker container:
```bash
# from your worker container
yarn command:prod cron:messaging:messages-import
yarn command:prod cron:messaging:message-list-fetch
yarn command:prod cron:calendar:calendar-event-list-fetch
yarn command:prod cron:calendar:calendar-events-import
yarn command:prod cron:messaging:ongoing-stale
yarn command:prod cron:calendar:ongoing-stale
yarn command:prod cron:workflow:automated-cron-trigger
```

## Email Configuration

1. Go to **Settings → Admin Panel → Configuration Variables**
2. Find the **Email** section
3. Configure your SMTP settings:

<Tabs>

  <Tab title="Gmail">

  You will need to provision an [App Password](https://support.google.com/accounts/answer/185833).
  - EMAIL_DRIVER=smtp
  - EMAIL_SMTP_HOST=smtp.gmail.com
  - EMAIL_SMTP_PORT=465
  - EMAIL_SMTP_USER=gmail_email_address
  - EMAIL_SMTP_PASSWORD='gmail_app_password'

  </Tab>

  <Tab title="Office365">

  Keep in mind that if you have 2FA enabled, you will need to provision an [App Password](https://support.microsoft.com/en-us/account-billing/manage-app-passwords-for-two-step-verification-d6dc8c6d-4bf7-4851-ad95-6d07799387e9).
  - EMAIL_DRIVER=smtp
  - EMAIL_SMTP_HOST=smtp.office365.com
  - EMAIL_SMTP_PORT=587
  - EMAIL_SMTP_USER=office365_email_address
  - EMAIL_SMTP_PASSWORD='office365_password'

  </Tab>

  <Tab title="smtp4dev">

  **smtp4dev** is a fake SMTP email server for development and testing.
  - Run the smtp4dev image: `docker run --rm -it -p 8090:80 -p 2525:25 rnwood/smtp4dev`
  - Access the smtp4dev ui here: [http://localhost:8090](http://localhost:8090)
  - Set the following variables:
    - EMAIL_DRIVER=smtp
    - EMAIL_SMTP_HOST=localhost
    - EMAIL_SMTP_PORT=2525

  </Tab>

</Tabs>

<Warning>
**Environment-only mode:** If you set `IS_CONFIG_VARIABLES_IN_DB_ENABLED=false`, add these variables to your `.env` file instead.
</Warning>

## S3 Storage

<Warning>
By default, Twenty stores uploaded files on the local filesystem. For production deployments, use S3 or an S3-compatible service (MinIO, DigitalOcean Spaces, etc.) to ensure files persist across container restarts and scale across multiple server instances.
</Warning>

Set `STORAGE_TYPE=S_3` and configure the `STORAGE_S3_*` variables through the admin panel or `.env`. See the [config-variables.ts reference](https://github.com/twentyhq/twenty/blob/main/packages/twenty-server/src/engine/core-modules/twenty-config/config-variables.ts) for the full list of S3 variables.

When using S3 with CORS-dependent features (e.g. in-browser file downloads), make sure your bucket allows your Twenty frontend origin in its CORS configuration.

## Logic Functions & Code Interpreter

Twenty supports logic functions for workflows and the code interpreter for AI data analysis. Both run user-provided code and require explicit configuration for security.

### Security Defaults

**In production (NODE_ENV=production):** Both logic functions and code interpreter default to **Disabled**. You must explicitly enable them with `LOGIC_FUNCTION_TYPE` and `CODE_INTERPRETER_TYPE` if you need these features.

**In development (NODE_ENV=development):** Both default to **LOCAL** for convenience when running locally.

<Warning>
**Security Notice:** The local driver (`LOGIC_FUNCTION_TYPE=LOCAL` or `CODE_INTERPRETER_TYPE=LOCAL`) runs code directly on the host in a Node.js process with no sandboxing. It should only be used for trusted code in development. For production deployments handling untrusted code, use `LOGIC_FUNCTION_TYPE=LAMBDA` or `CODE_INTERPRETER_TYPE=E2B` (with sandboxing), or keep them disabled.
</Warning>

### Logic Functions - Available Drivers

| Driver | Environment Variable | Use Case | Security Level |
|--------|---------------------|----------|----------------|
| Disabled | `LOGIC_FUNCTION_TYPE=DISABLED` | Disable logic functions entirely | N/A |
| Local | `LOGIC_FUNCTION_TYPE=LOCAL` | Development and trusted environments | Low (no sandboxing) |
| Lambda | `LOGIC_FUNCTION_TYPE=LAMBDA` | Production with untrusted code | High (hardware-level isolation) |

### Logic Functions - Recommended Configuration

**For development:**
```bash
LOGIC_FUNCTION_TYPE=LOCAL  # default when NODE_ENV=development
```

**For production (AWS):**
```bash
LOGIC_FUNCTION_TYPE=LAMBDA
LOGIC_FUNCTION_LAMBDA_REGION=us-east-1
LOGIC_FUNCTION_LAMBDA_ROLE=arn:aws:iam::123456789:role/your-lambda-role
LOGIC_FUNCTION_LAMBDA_ACCESS_KEY_ID=your-access-key
LOGIC_FUNCTION_LAMBDA_SECRET_ACCESS_KEY=your-secret-key
```

**To disable logic functions:**
```bash
LOGIC_FUNCTION_TYPE=DISABLED  # default when NODE_ENV=production
```

### Code Interpreter - Available Drivers

| Driver | Environment Variable | Use Case | Security Level |
|--------|---------------------|----------|----------------|
| Disabled | `CODE_INTERPRETER_TYPE=DISABLED` | Disable AI code execution | N/A |
| Local | `CODE_INTERPRETER_TYPE=LOCAL` | Development only | Low (no sandboxing) |
| E2B | `CODE_INTERPRETER_TYPE=E_2_B` | Production with sandboxed execution | High (isolated sandbox) |

<Note>
When using `LOGIC_FUNCTION_TYPE=DISABLED` or `CODE_INTERPRETER_TYPE=DISABLED`, any attempt to execute will return an error. This is useful if you want to run Twenty without these capabilities.
</Note>