Environment variables for Self-hosted Retool deployments.
Environment variables control or override certain functions and characteristics of Self-hosted Retool instances. Some Retool features require you to set environment variables, such as SSO or Source Control.
You should only configure environment variables when needed. You must restart your instance after setting any variables for them to take effect.
General
General environment variables available for use with Self-hosted Retool deployments.
BASE_DOMAIN
The full URL of your Retool deployment for user invitations and password resets. This also needs to be set if you dynamically set callback URLs on protected resources.
If unset, Retool attempts to determine the base domain automatically but cannot do so if your deployment is behind a proxy server.
BASE_DOMAIN=https://retool.example.com
CUSTOM_API_KEY
A Custom API key to override Retool-generated API keys.
CUSTOM_API_KEY=key_545567563
CUSTOM_RETOOL_SANDBOX_RESTRICTIONS
Only configure custom sandbox restrictions if you are comfortable with the security implications.
The JavaScript sandbox restrictions to allow. Specify space-separated values for multiple restrictions.
allow-downloads: Allow downloadsallow-popups: Allow pop-upsallow-modals: Allow modals
If unset, no restrictions are allowed.
CUSTOM_RETOOL_SANDBOX_RESTRICTIONS=allow-downloads allow-modals
DEBUG
Whether to enable verbose logging for debugging purposes. Set DEBUG to 1 to enable verbose logging.
DEBUG=1
DISABLE_INTERCOM
Requires Self-hosted Retool v2.72.28 or later.
Disable Retool's support widget in the frontend. You can still contact Retool at [email protected]
DISABLE_INTERCOM=true
DISABLE_MEMORY_AND_CPU_USAGE_LOGGING
Disable logging of CPU and memory usage.
DISABLE_MEMORY_AND_CPU_USAGE_LOGGING=true
DISABLE_PUBLIC_PAGES
Disable public access of Retool apps.
DISABLE_PUBLIC_PAGES=true
DISABLE_FORWARDABLE_COOKIE_DECODING
Requires Self-hosted Retool v2.90 or later.
Disable automatic cookie decoding when using forwardable cookies.
DISABLE_FORWARDABLE_COOKIE_DECODING=true
DOMAINS
Used to set EntityID in our SAML requests and obtain SSL certificate when setting up HTTPS.
HIDE_PROD_AND_STAGING_TOGGLES
Hide Production and Staging toggles in creator and user mode interfaces.
HIDE_PROD_AND_STAGING_TOGGLES=true
HTML_ESCAPE_RETOOL_EXPRESSIONS
Escape HTML expressions within curly braces ({{ }}). If unset, the default is false.
HTML_ESCAPE_RETOOL_EXPRESSIONS=true
LOG_AUDIT_EVENTS
Log all audit events.
LOG_AUDIT_EVENTS=true
LOG_LEVEL
The level of information logged to stdout. Specify space-separated values for multiple restrictions.
info: Default logging level.verbose: More verbose logs for git syncing, authentication, etc.debug: Raw debug logs.
LOG_LEVEL=debug
NODE_ENV
The environment of the instance. Defaults to production and cannot be changed.
NODE_TLS_REJECT_UNAUTHORIZED
When set to 0, disables certificate validation for TLS connections. This setting is insecure and not recommended for production instances.
NODE_TLS_REJECT_UNAUTHORIZED=0
NUM_WORKERS
The number of workers for the instance.
NUM_WORKERS=500
RETOOL_EXPOSED_{NAME}
Use the RETOOL_EXPOSED_ prefix to store secrets that you can use when configuring resources.
RETOOL_EXPOSED_DB_USERNAME=db_user
RETOOL_EXPOSED_DB_PASSWORD=4356748i7rkjthrtHBHNHRFB
Authentication
Authentication environment variables available for use with Self-hosted Retool deployments.
CLIENT_ID
A Google OAuth client app ID for OAuth-based authentication with Google (e.g., Google SSO or using a Google Sheets resource).
CLIENT_ID=1234567890-abcd.apps.googleusercontent.com
CLIENT_SECRET
A Google OAuth client app secret for OAuth-based authentication with Google (e.g., Google SSO or using a Google Sheets resource).
CLIENT_SECRET=1234567890-abcd.apps.googleusercontent.com
CUSTOM_LOGOUT_REDIRECT
A URL that users are redirected to after logging out of Retool.
CUSTOM_LOGOUT_REDIRECT=https://example.com/logout/success
CUSTOM_OAUTH2_SSO_ACCESS_TOKEN_LIFESPAN_MINUTES
The lifespan, in minutes, of custom OpenID provider tokens. If unset, the default lifespan is 120.
CUSTOM_OAUTH2_SSO_ACCESS_TOKEN_LIFESPAN_MINUTES=60
CUSTOM_OAUTH2_SSO_AUDIENCE
An identifier for a resource to which users should have access upon completion of an OpenID authorization process.
CUSTOM_OAUTH2_SSO_AUDIENCE = https://retool.auth0.com/api/v2
CUSTOM_OAUTH2_SSO_JWT_ROLES_KEY
An array of strings where each string represents an OpenID group name. This setting is used with CUSTOM_OAUTH2_SSO_ROLE_MAPPING to map groups to Retool permission groups.
CUSTOM_OAUTH2_SSO_JWT_ROLES_KEY=idToken.groups
CUSTOM_OAUTH2_SSO_ROLE_MAPPING
The mapping of roles from your OpenID provider to Retool permission groups.
CUSTOM_OAUTH2_SSO_ROLE_MAPPING=devops -> admin, support -> viewer
CUSTOM_OAUTH2_SSO_USERINFO_URL
The endpoint for Retool make an additional request for a fat token containing all available claims from your OpenID SSO provider.
CUSTOM_OAUTH2_SSO_USERINFO_URL=https://yourcompany.okta.com/oauth2/v1/userinfo
DEFAULT_GROUP_FOR_DOMAINS
The default Retool user group for a Google SSO domain. You can specify space-separated values to map multiple domain and group pairs.
Default groups only applies to new users who sign up using SSO, not existing users signing in.
DEFAULT_GROUP_FOR_DOMAINS=example1.org -> admin, example2.com -> viewer
DISABLE_USER_PASS_LOGIN
Requires Self-hosted Retool v2.68.18 or later.
Disable username and password authentication. If true, users can only log in using SSO.
DISABLE_USER_PASS_LOGIN=true
INVITES_PER_DAY
The number of invites that can be sent to users. If unset, the default is 50.
Use this environment variable if you encounter rate limits on invites.
INVITES_PER_DAY=100
JWT_SECRET
The JWT secret token to sign requests for authentication with Retool's backend API server. If changed, all active user login sessions are invalidated.
JWT_SECRET=676765765327645bvbfgbsfhfbgr
PRESERVE_PASSWORDS_FIRST_GOOGLE_LOGIN
Requires Self-hosted Retool v2.75.4 or later.
Prevent Retool resetting your password when logging in with Google for the first time.
PRESERVE_PASSWORDS_FIRST_GOOGLE_LOGIN=true
RESTRICTED_DOMAIN
Restrict users from logging in unless they use SSO for the specified domain. This value must match your email domain. Specify comma-separated values for multiple domains.
This removes the Retool username and password fields from the sign in page. When you deploy Self-hosted Retool, you must first sign up with a username and password. You can then enable SSO-only logins with this variable.
RESTRICTED_DOMAIN=example.com,example.org
SAML_FIRST_NAME_ATTRIBUTE
The first name attribute in the SAML response. If unset, the default is firstName.
SAML_FIRST_NAME_ATTRIBUTE=nameFirst
SAML_LAST_NAME_ATTRIBUTE
The first name attribute in the SAML response. If unset, the default is lastName.
SAML_LAST_NAME_ATTRIBUTE=nameLast
SAML_GROUPS_ATTRIBUTE
The groups attribute in the SAML response. If unset, the default is groups.
SAML_GROUPS_ATTRIBUTE=userGroups
SAML_SYNC_GROUP_CLAIMS
Sync Retool group memberships using the retool- prefix with the groups listed in SAML_GROUPS_ATTRIBUTE.
The prefix is not shown in the Retool interface.
SAML_SYNC_GROUP_CLAIMS=true
SCIM_AUTH_TOKEN
A secret token shared with your SSO provider to provision user accounts.
SCIM_AUTH_TOKEN=token
SCIM_LOG_FULL_REQUESTS
Log SCIM requests to the Retool API container logs.
SCIM_LOG_FULL_REQUESTS=true
SENDING_INVITES_WITH_EMAIL_DISABLED
Allow user invites without pinging Retool's user invitation server. You must enable this if you have an airgapped deployment.
SENDING_INVITES_WITH_EMAIL_DISABLED=true
TRIGGER_OAUTH_2_SSO_LOGIN_AUTOMATICALLY
Automatically start the Oauth 2 SSO login flow when users navigate to your Retool instance.
Use either TRIGGER_OAUTH_2_SSO_LOGIN_AUTOMATICALLY or TRIGGER_SAML_LOGIN_AUTOMATICALLY, you cannot enable both.
TRIGGER_OAUTH_2_SSO_LOGIN_AUTOMATICALLY=true
TRIGGER_SAML_LOGIN_AUTOMATICALLY=false
TRIGGER_SAML_LOGIN_AUTOMATICALLY
Automatically start the SAML SSO login flow when users navigate to your Retool instance.
Use either TRIGGER_SAML_LOGIN_AUTOMATICALLY or TRIGGER_OAUTH_2_SSO_LOGIN_AUTOMATICALLY, you cannot enable both.
TRIGGER_OAUTH_2_SSO_LOGIN_AUTOMATICALLY=false
TRIGGER_SAML_LOGIN_AUTOMATICALLY=true
USE_SHORT_SESSIONS
Restrict session length to 12 hours. If unset, default session length is one week.
USE_SHORT_SESSIONS=true
Cookies
Cookies environment variables available for use with Self-hosted Retool deployments.
COOKIE_INSECURE
Whether to send authentication requests using insecure cookies. Set COOKIE_INSECURE to true if your Retool deployment uses a non-HTTPS URL or IP address. This is typically used when a Retool deployment is not yet configured with a custom domain.
Set COOKE_INSECURE to false if you need to embed private Retool applications.
COOKIE_INSECURE=false
FORWARDABLE_SAME_DOMAIN_COOKIES_ALLOWLIST
When you have cookies scoped to your primary domain, you can use this variable to include those cookies in requests from the subdomain you host Retool on to your primary domain.
FORWARDABLE_SAME_DOMAIN_COOKIES_ALLOWLIST=cookieName
Git syncing
Git syncing environment variables available for use with Self-hosted Retool deployments.
DISABLE_PROTECTED_APPS_SYNCING
Disable polling of GitHub and syncing changes from the Source Control repository. This only pauses the syncing process so apps remain protected.
DISABLE_PROTECTED_APPS_SYNCING=true
DISABLE_GIT_SYNCING
Disable git syncing and stop pulling changes from the connected repository.
DISABLE_GIT_SYNCING=true
Queries
Queries environment variables available for use with Self-hosted Retool deployments.
CLIENT_MAX_BODY_SIZE
On the https-portal container, specify the maximum request body size, in bytes, megabytes (M), or kilobytes (K). Any upload that exceeds this limit results in a 413 HTTP error. Set to 0 to allow bodies of any size.
CLIENT_MAX_BODY_SIZE=40M
DBCONNECTOR_NUM_WORKERS
The number of workers for the instance, with a maximum of 3. If unset, defaults to 1 or the number of CPUs.
DBCONNECTOR_NUM_WORKERS=1
DBCONNECTOR_POSTGRES_POOL_MAX_SIZE
The PostgreSQL connection pool maximum size. If unset, the default is 10.
DBCONNECTOR_POSTGRES_POOL_MAX_SIZE=7
DBCONNECTOR_QUERY_TIMEOUT_MS
The duration, in milliseconds, for queries to run before timing out. If unset, the default duration is 120000.
If your Retool deployment is behind a load balancer, increase the load balancer's timeout by a proportionate amount.
DBCONNECTOR_QUERY_TIMEOUT_MS=360000
ENABLE_CUSTOM_PLATFORM_LEVEL_AUTH_STEPS
Allow configuration of custom authentication steps for users to perform whenever they log into Retool.
ENABLE_CUSTOM_PLATFORM_LEVEL_AUTH_STEPS=true
HIDE_ALL_HEADERS_IN_AUDIT_LOG_EVENTS
Prevent all query headers and cookies from being added to audit log entries.
HIDE_ALL_HEADERS_IN_AUDIT_LOG_EVENTS=true
KEEPALIVE_TIMEOUT
The keep alive timeout for queries, in seconds. Queries that exceed this limit results in a 514 HTTP error.
KEEPALIVE_TIMEOUT=1000
PROXY_CONNECT_TIMEOUT
The proxy connect timeout for queries, in seconds. Queries that exceed this limit results in a 514 HTTP error.
PROXY_CONNECT_TIMEOUT=1000
PROXY_SEND_TIMEOUT
The proxy send timeout for queries, in seconds. Queries that exceed this limit results in a 514 HTTP error.
PROXY_SEND_TIMEOUT=1000
PROXY_READ_TIMEOUT
The proxy read timeout for queries, in seconds. Queries that exceed this limit results in a 514 HTTP error.
PROXY_READ_TIMEOUT=1000
Redis
Redis environment variables available for use with Self-hosted Retool deployments.
REDIS_DB
The database number for read and write operations, between 0 and 15.
If unsure, set to the default port of 0.
REDIS_DB=0
REDIS_HOST
The hostname of the Redis reader endpoint that connects the Redis instance as a caching layer.
REDIS_HOST=redis-retool
REDIS_PASSWORD
The password for the Redis instance.
REDIS_PASSWORD=pw
REDIS_PORT
The port number for the Redis instance. By default, this should be 6379.
REDIS_PORT=6379
REDIS_TLS
Connect to the Redis instance if using TLS.
REDIS_TLS=true
Resources
Resources environment variables available for use with Self-hosted Retool deployments.
ENABLE_CLIENT_SIDE_CUSTOM_AUTH_BROWSER_CALLS
Allow editors to configure custom authentication steps for resources that make REST API calls directly from the browser. If true, these requests include all browser credentials, even cross-origin calls.
ENABLE_CLIENT_SIDE_CUSTOM_AUTH_BROWSER_CALLS=true
ENCRYPTION_KEY
Encrypts data stored in the PostgreSQL database (e.g., database credentials, SSH keys, etc).
Make sure to keep track of this key in a location outside of your Retool instance(s). If you change this key, you will lose access to all resources that were created before the change.
ENCRYPTION_KEY=key
USE_GCM_ENCRYPTION
Use the AES-192-GCM authenticated encryption method. If unset, default encryption of AES-192-CBC is used.
If USE_GCM_ENCRYPTION is in use, ENCRYPTION_KEY must be 24 characters in length. If you change this setting, you will lose access to all resources encrypted using the other algorithm.
USE_GCM_ENCRYPTION=true
Source Control
Source Control environment variables available for use with Self-hosted Retool deployments.
BITBUCKET_USER
The Bitbucket username.
BITBUCKET_USER=retool
BITBUCKET_APP_PASSWORD
The Bitbucket app password.
BITBUCKET_APP_PASSWORD=loDJlwRetoolTYXOFbO
BITBUCKET_WORKSPACE
The name of the Bitbucket workspace.
BITBUCKET_WORKSPACE=retool-space
BITBUCKET_REPO
The name of the Bitbucket repository.
BITBUCKET_REPO=retool-apps
BITBUCKET_MAIN_BRANCH
The default branch for the Bitbucket repository.
BITBUCKET_MAIN_BRANCH=main
CODE_COMMIT_AWS_ACCESS_KEY_ID
The AWS CodeCommit Access Key ID.
CODE_COMMIT_AWS_ACCESS_KEY_ID=AKIAWS3BACWHP6QW6VB2
CODE_COMMIT_AWS_SECRET_ACCESS_KEY
The AWS CodeCommit Secret Access Key.
CODE_COMMIT_AWS_SECRET_ACCESS_KEY=loDJlwRetoolTYXOFbO
CODE_COMMIT_AWS_DEFAULT_REGION
The AWS CodeCommit repository region.
CODE_COMMIT_AWS_DEFAULT_REGION=us-east-1
CODE_COMMIT_REPOSITORY_NAME
The name of the AWS CodeCommit repository.
CODE_COMMIT_REPOSITORY_NAME=retool-apps
CODE_COMMIT_MAIN_BRANCH
The default branch for the AWS CodeCommit repository.
CODE_COMMIT_MAIN_BRANCH=main
CODE_COMMIT_HTTPS_USERNAME
The AWS CodeCommit HTTPS username.
CODE_COMMIT_HTTPS_USERNAME=retool-https-username
CODE_COMMIT_HTTPS_PASSWORD
The AWS CodeCommit HTTPS password.
CODE_COMMIT_HTTPS_PASSWORD=retool-https-password
GITHUB_APP_ID
The GitHub App ID.
GITHUB_APP_ID=12345
GITHUB_APP_INSTALLATION_ID
The GitHub App installation ID.
GITHUB_APP_INSTALLATION_ID=54321
GITHUB_APP_PRIVATE_KEY
The base64-encoded value of the generated GitHub private key. This value should only span one line.
If you are using a Kubernetes Secret, you must base64 encode this value twice.
GITHUB_APP_PRIVATE_KEY=...
GITLAB_URL
The base GitLab URL.
GITLAB_URL=https://gitlab.com
GITLAB_URL=https://gitlab.example.com
GITLAB_PROJECT_ACCESS_TOKEN
The GitLab project access token for authentication.
GITLAB_PROJECT_ACCESS_TOKEN=glpat-123xyzabc456
GITLAB_PROJECT_ID
The GitLab project ID.
GITLAB_PROJECT_ID=12345
GITLAB_MAIN_BRANCH
The default branch for the GitLab project.
GITLAB_MAIN_BRANCH=main
GITLAB_ORGANIZATION_NAME
The GitLab organization name. This can be a username if the GitLab project is not part of an organization.
GITLAB_ORGANIZATION_NAME=company
GITLAB_REPOSITORY_NAME
The GitLab repository name.
GITLAB_REPOSITORY_NAME=product-dev
GITLAB_PROJECT_SLUG
The GitLab project's URL PATH.
GITLAB_PROJECT_SLUG=company/eng/product-dev
VERSION_CONTROL_LOCKED
Requires Self-hosted Retool v2.91 or later.
Creates a read-only instance of Retool where:
- New apps cannot be created
- Existing apps cannot be edited
- Existing apps cannot be marked as protected
Storage database
Storage database environment variables available for use with Self-hosted Retool deployments.
DATABASE_MIGRATIONS_TIMEOUT_SECONDS
Requires Self-hosted Retool v2.82 or later.
The duration, in seconds, for migrations to run before timing out. If unset, the default is 300.
Consider setting a higher value if you're upgrading to another major version of Self-hosted Retool or the upgrade includes changes from multiple minor versions.
DATABASE_MIGRATIONS_TIMEOUT_SECONDS=900
POSTGRES_CUSTOM_SSL_CA_FILE_NAME
The name of the custom SSL CA file to use. This is required when configuring Google Cloud SQL as the database to use instead of Retool's PostgreSQL database.
POSTGRES_CUSTOM_SSL_CA_FILE_NAME=filename
POSTGRES_CUSTOM_SSL_CERT_FILE_NAME
The name of the custom SSL certificate file to use. This is required when configuring Google Cloud SQL as the database to use instead of Retool's PostgreSQL database.
POSTGRES_CUSTOM_SSL_CERT_FILE_NAME=filename
POSTGRES_CUSTOM_SSL_KEY_FILE_NAME
The name of the custom SSL key file to use. This is required when configuring Google Cloud SQL as the database to use instead of Retool's PostgreSQL database.
POSTGRES_CUSTOM_SSL_KEY_FILE_NAME=filename
POSTGRES_CUSTOM_SSL_CERT_PATH
The path to your custom certificate when connecting to your Retool database.
POSTGRES_CUSTOM_SSL_CERT_PATH=/var/data/certs
POSTGRES_SSL_ENABLED
Force SSL connections to your Retool PostgreSQL storage database.
POSTGRES_SSL_ENABLED=true
POSTGRES_SSL_REJECT_UNAUTHORIZED
Reject unauthorized SSL connections if POSTGRES_SSL_ENABLED is true.
You must enable this if using self-signed certificates on 2.95+.
POSTGRES_SSL_REJECT_UNAUTHORIZED=true