Environment Variables

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


You must restart your instance whenever you modify environment variables.

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:

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 private 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_OAUTH2_SSO_AUDIENCEProvides an identifier for a resource Retool users should have access to after completing an OpenID authorization process. If this variable is not specified, users receive an opaque JSON web token (JWT), and the accessToken is unpopulated.
CUSTOM_OAUTH2_SSO_USERINFO_URLSpecify the endpoint where Retool can request all available claims from your OpenID SSO provider. See Thin tokens and fat tokens for more information.
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_FORWARDABLE_COOKIE_DECODINGDisables automatic cookie decoding when using forwardable cookies. If true, cookies will remain encoded. Requires v2.90 or higher.
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 true 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.
INVITES_PER_DAYThe number of invites that can be sent to users (defaults to 50). Use this environment variable if you encounter rate limits on invites.
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.
NUM_WORKERSSets the number of workers for the Retool instance.
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
for the value of this variable.
POSTGRES_SSL_ENABLEDSet to true to force SSL connections to your Retool Postgres DB.
POSTGRES_SSL_REJECT_UNAUTHORIZEDIf the POSTGRES_SSL_ENABLED environment variable is set to true, POSTGRES_SSL_REJECT_UNAUTHORIZED can be used to reject unauthorized SSL connections. You must enable this if using self-signed certificates on 2.95+.
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..
SAML_FIRST_NAME_ATTRIBUTEThe first name attribute in the SAML response (defaults to "firstName").
SAML_LAST_NAME_ATTRIBUTEThe last name attribute in the SAML response (defaults to "lastName").
SAML_GROUPS_ATTRIBUTEThe groups attribute in the SAML response (defaults to "groups").
SAML_SYNC_GROUP_CLAIMSSync Retool group memberships beginning with the retool- prefix with the groups listed in SAML_GROUPS_ATTRIBUTE. The prefix is stripped in the Retool UI (e.g., retool-admin in the SAML response would be admin within Retool).
SCIM_AUTH_TOKENA secret token shared with your 3rd party SSO provider (e.g. Okta) to provision user accounts.
SCIM_LOG_FULL_REQUESTSLogs SCIM requests to the Retool API container logs. Defaults to false.
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. Works with Source Control for Retool versions 2.91 and later.
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.
GITLAB_URLYour base GitLab URL. For GitLab Cloud, this is always https://gitlab.com. For GitLab self-managed, this is the URL where your instance is hosted.
GITLAB_PROJECT_ACCESS_TOKENRetool uses GitLab’s Project access tokens for authenticating against the GitLab API. Each token gives Retool read and write API access to a specific GitLab project.

See the setup instructions to learn how to generate an access token.
GITLAB_PROJECT_IDEvery GitLab project has a numerical project ID. You can find this ID listed below the project's name on the project's homepage.

For example, the project ID for the GitLab project is 278964.
GITLAB_MAIN_BRANCHThe default branch for your GitLab project.
GITLAB_ORGANIZATION_NAME, GITLAB_REPOSITORY_NAME OR GITLAB_PROJECT_SLUGSee this section in "Setting up Gitlab" for more information.

Did this page help you?