Environment Variables

Users with self-hosted Retool instances can set the following environment variables.

🚧

You must restart your instance whenever you modify environment variables.

VariableDescription
BASE_DOMAINThe BASE_DOMAIN variable helps us create links for your users, like new user invitations and forgotten password resets. The backend tries to guess this, but it can be incorrect if there’s a proxy in front of the actual website.

Please include the full domain where Retool is deployed, like this:

BASE_DOMAIN=https://retool.yourwebsite.com
CLIENT_IDUsed for our Google Sheets integration and/or Google SSO.
CLIENT_MAX_BODY_SIZEUsed in the nginx container https-portal to limit query response sizes. Query response sizes above this limit result in 413 HTTP errors.
CLIENT_SECRETUsed for our Google Sheets integration and/or Google SSO.
COOKIE_INSECURESends auth requests with insecure cookies — set to true if hosting Retool on a non-HTTPS URL or raw IP address. This is typically used if you haven’t deployed Retool on a custom domain yet.

When embedding non-public Retool applications, this must be set to false
CUSTOM_API_KEYProvide a custom API key (overrides Retool-generated API keys).
CUSTOM_LOGOUT_REDIRECTSet a custom URL to redirect users to on logout. This is useful, for example, if you wish to redirect users to a URL that logs them out globally from your SSO provider.
CUSTOM_OAUTH2_SSO_ACCESS_TOKEN_LIFESPAN_MINUTESA value in minutes. Allows a custom token lifespan to be set for use with Custom OpenId providers when accessing variables like %USER_OAUTH2_ACCESS_TOKEN%
CUSTOM_RETOOL_SANDBOX_RESTRICTIONSCustomize the Retool JavaScript sandbox restrictions, e.g., to enable downloads from Retool JavaScript queries set this to allow-downloads. Currently only allow-popups, allow-downloads, and allow-modals are supported (space-separate to enable multiple restrictions). Note: only set this environment variable if you are comfortable with the security implications.
DATABASE_MIGRATIONS_TIMEOUT_SECONDSDefault 300 seconds (5 minutes).

Controls how many seconds migrations will be retried in each running container. Useful to set to a higher value if migrations timeout OR upgrading Retool major versions, or several minor versions.

Requires v2.82 or higher
DBCONNECTOR_QUERY_TIMEOUT_MSSet this environment variable if you need to run queries that take more than 2 minutes to complete. Specify the timeout in milliseconds. For example, the default value is 120000 ms (2 minutes)

Note: if you have Retool behind a load balancer, make sure you also increase the load balancer's timeout by a commensurate amount.
DEBUGSet DEBUG=1 to enable verbose logging.
DEFAULT_GROUP_FOR_DOMAINSMaps Google SSO domains to Retool groups. Example: DEFAULT_GROUP_FOR_DOMAINS=retool.com -> admin, foo.com -> viewer

Note: only applies to new users signing up via SSO. Does not apply to existing users signing in.
DISABLE_GIT_SYNCINGUsed for git syncing. Set to true on a read-only instance to disable pulling new changes from the connected GitHub repository.
DISABLE_INTERCOMSet to true to stop Intercom from being loaded in the frontend. You can still contact Retool support by emailing us at [email protected].

Requires v2.72.28 or higher
DISABLE_MEMORY_AND_CPU_USAGE_LOGGINGSet to true to disable logging of CPU usage % and memory stats.
DISABLE_PROTECTED_APPS_SYNCINGSet this variable to false to disable Retool from polling GitHub and syncing down changes from the Source Control repository. This will not unprotect your apps, but pause the syncing process.
DISABLE_PUBLIC_PAGESControls public access links. Set to true to disable public access across all apps.
DISABLE_USER_PASS_LOGINRestricts login to SSO (removes username & password inputs from sign in page).

Requires v2.68.18 or higher
DOMAINSUsed to set EntityID in our SAML requests and obtain SSL certificate when setting up HTTPS.
ENABLE_CLIENT_SIDE_CUSTOM_AUTH_BROWSER_CALLSSet this environment variable to allow editors to set Resource custom authentication steps that make REST API calls directly from the browser. Browser credentials will be included, even for cross-origin calls, with these requests.
ENABLE_CUSTOM_PLATFORM_LEVEL_AUTH_STEPSSet this environment variable to allow configuring custom authentication steps that are performed whenever a user logs in to Retool. These steps are defined under Organization Settings -> Authentication and allow you to define variables that can be used in any REST API resources (e.g. for tokens that shared across multiple resources).
ENCRYPTION_KEYEncrypts things that are stored in the Postgres DB (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.
FORWARDABLE_SAME_DOMAIN_COOKIES_ALLOWLISTWhen 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.
GITHUB_APP_ID GITHUB_APP_INSTALLATION_ID GITHUB_APP_PRIVATE_KEYUse these 3 variables in order to setup the Source Control feature.
HIDE_ALL_HEADERS_IN_AUDIT_LOG_EVENTSPrevents all query headers (including cookies) from getting added to audit log entries.
HIDE_PROD_AND_STAGING_TOGGLESSet to true to hide prod and staging toggles in the UI, in both edit mode and end user mode. This is useful for reducing confusion when you aren’t managing prod and staging in Retool, e.g. via Git sync between 2+ instances instead.
JWT_SECRETUsed to sign requests for authentication to Retool's backend API server. If this is reset, all active user login sessions are invalidated and users need to log in again.
LOG_AUDIT_EVENTSSet to true to print audit logs to log. Defaults to false.
LOG_LEVELControls how much to log to stdout:

Possible values:
"info": default logging level
"verbose": more verbose logs for git syncing, auth systems, etc.
"debug": raw debug logs
NODE_ENVSet to "production" by default, you are not able to configure to other values.
POSTGRES_CUSTOM_SSL_CA_FILE_NAME POSTGRES_CUSTOM_SSL_CERT_FILE_NAME POSTGRES_CUSTOM_SSL_KEY_FILE_NAMEIf you want to use Google Cloud SQL as the Retool DB, all 3 of these are required.
POSTGRES_CUSTOM_SSL_CERT_PATHSet this environment variable if you need to use a custom certificate when connecting to your Retool DB.

ex. Let's say your certificate is mounted to /var/data/certs/certificate.pem
in your Docker container, you would use
/var/data/certs
for the value of this variable.
POSTGRES_SSL_ENABLEDSet to true to force SSL connections to your Retool Postgres DB.
PRESERVE_PASSWORDS_FIRST_GOOGLE_LOGINTo preserve account security, Retool resets your password the first time you log in with Google. Set this environment variable to true to opt out of this behavior.

Requires v2.75.4 or higher
REDIS_DBNumber between 0-15 to specify the database within Redis to read/write from. If unsure, set to 0, as that is the default port.
REDIS_HOSTThe hostname of the Redis reader endpoint, used to connect Redis to Retool as a caching layer. More info here.
REDIS_PASSWORDPassword for Redis instance, if password was set during setup.
REDIS_PORTPort number to connect to your Redis instance. By default, this should be 6379.
REDIS_TLSBoolean set to true if and only if TLS is enabled.
RESTRICTED_DOMAINRestricts login to SSO (removes username & password inputs from sign in page).

Note: when deploying Retool, you must first sign up via username & password before you can enable SSO-only login with this environment variable. (In other words, the first user must sign up with username & password.)

The value of this variable should match your email domain.

Example: RESTRICTED_DOMAIN=yourcompany.com

If you want to authorize multiple domains, use a comma-separated list: RESTRICTED_DOMAIN=acme.com,acme.dev
RETOOL_EXPOSED_XYZAny .env variable of this format is accessible in the Resource configuration screen. More info here..
SCIM_AUTH_TOKENA secret token shared with your 3rd party SSO provider (e.g. Okta) to provision user accounts.
SENDING_INVITES_WITH_EMAIL_DISABLEDSet to true to allow user invites without pinging the invite server (if Retool tries to connecting to the invite server but can’t, you won’t be able to add new users). Useful for air-gapped deployments.
TRIGGER_OAUTH_2_SSO_LOGIN_AUTOMATICALLY TRIGGER_SAML_LOGIN_AUTOMATICALLYSet one of these environment variables to true to enable automatically starting the SSO flow for SAML login or Oauth2 SSO login, respectively. That is, when an unauthenticated user navigates to retool.yourdomain.xyz they will automatically be sent into the SSO workflow.
USE_GCM_ENCRYPTIONUsed for Encryption. Set to true to utilize an authenticated encryption method (AES-192-GCM) otherwise it will default to utilizing AES-192-CBC.

When using GCM, 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_SHORT_SESSIONSSet to true if you want to enable short sessions. This requires users to login every 12 hours (default is 1 week if this is not enabled, which gets extended at each login). This works with SSO as well.
VERSION_CONTROL_LOCKEDUsed for git syncing. Set to true if you want this Retool instance to only pull from (not push to) to your repository.
KEEPALIVE_TIMEOUT PROXY_CONNECT_TIMEOUT PROXY_SEND_TIMEOUT PROXY_READ_TIMEOUTUsed in the nginx container https-portal to time out queries. Queries above these timeouts result in a 514 HTTP error.

The values are in seconds.

Did this page help you?