Environment variables reference
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.
ALLOW_SAME_ORIGIN_OPTION
When ALLOW_SAME_ORIGIN_OPTION
is set to true
, components running in iframes in Retool, such as IFrame and custom components, can use the allow-same-origin flag in the sandbox attribute of their iframes. IFrames without the allow-same-origin
flag have severe restrictions, so it can be useful to set ALLOW_SAME_ORIGIN_OPTION
to true
.
When ALLOW_SAME_ORIGIN_OPTION
is set to true
, you should also set SANDBOX_DOMAIN
. If ALLOW_SAME_ORIGIN_OPTION
is true
and SANDBOX_DOMAIN
is not set, then JavaScript run in iframe-based components is run in the base domain. This can be a security risk, as it allows malicious code that is run in iframe-based components greater access to cause harm. If ALLOW_SAME_ORIGIN_OPTION
is set to true
, SANDBOX_DOMAIN
should also be set.
If unset, the default value for ALLOW_SAME_ORIGIN_OPTION
is false
.
API_CALLS_PER_MIN
Retool uses a point system for rate limiting where endpoint requests cost a certain number of points. The default is 300 points in a 60 second window. If you exceed this, Retool blocks any subsequent API calls for 60 seconds. You can increase the number of points with the API_CALLS_PER_MIN
environment variable.
API_CALLS_PER_MIN=300
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. This doesn't apply to access tokens for embedding web apps, you still need to use the token generated in Retool.
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_IMAGE_PROXY
Disable the proxy used for public apps.
DISABLE_IMAGE_PROXY=true
DISABLE_INTERCOM
Disable Retool's support widget in the frontend. See Retool Support guidelines to learn how to contact Retool.
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. When set to true
, set DISABLE_IMAGE_PROXY
to true
as well to fully disable public access.
DISABLE_PUBLIC_PAGES=true
DISABLE_FORWARDABLE_COOKIE_DECODING
Disable automatic cookie decoding when using forwardable cookies.
DISABLE_FORWARDABLE_COOKIE_DECODING=true
DOMAINS
Used to set EntityID in SAML requests and obtain SSL certificate when setting up HTTPS.
DOMAINS=retool.your-domain.com -> http://api:3000
HIDE_PROD_AND_STAGING_TOGGLES
Hide Production and Staging toggles in creator and user mode interfaces.
HIDE_PROD_AND_STAGING_TOGGLES=true
HOST_HEADER_NAME
Retool backend expects Host
header to contain the host used in the original request. This is important for Spaces to work properly. If your self-hosted instance has a proxy or load-balancer in front of the Retool backend, you can specify a different header that contains the original host.
HOST_HEADER_NAME=x-forwarded-host
HTML_ESCAPE_RETOOL_EXPRESSIONS
Escape HTML expressions within curly braces ({{ }}
). If unset, the default is false
.
HTML_ESCAPE_RETOOL_EXPRESSIONS=true
HTTP_PROXY
The URL and port number for proxying HTTP connections.
HTTP_PROXY=http://example.com:8080
LICENSE_KEY
The license key for your self-hosted Retool instance.
LICENSE_KEY='retool-license-key'
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
DISABLE_AUDIT_TRAILS_LOGGING
Requires Self-hosted Retool v3.18 or later.
Disable all writes to audit logs.
DISABLE_AUDIT_TRAILS_LOGGING=true
NO_PROXY
Skip proxying HTTP requests from the specified URLs. Used when HTTP_PROXY
is set.
NO_PROXY=localhost,*.service.company
NODE_ENV
The environment of the instance. Must always be set to production
.
NODE_ENV=production
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 worker threads for the api
container. The default value is Math.min(Math.max(1, numCPUs), 3)
, where numCPUs
is the number of logical CPU cores on the machine determined by Node.js.
NUM_WORKERS=4
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
Only use underscores to separate characters and words. Other separators, including hyphens, cannot be used.
RETOOL_ENV
Used in SCIM provisioning and Source Control alerting to specify the environment name. Defaults to production
.
RETOOL_ENV=production
SANDBOX_DOMAIN
Retool evaluates javascript written by your builders in the browser. If a builder writes javascript that takes malicious actions, setting SANDBOX_DOMAIN
can help protect your other users.
Setting SANDBOX_DOMAIN
provides an alternative origin for the browser to use to run code written by builders. All builder-written code run in the browser is run in the origin defined by SANDBOX_DOMAIN
and is sandboxed from interacting with anything in your base domain. This includes authentication cookies for your Retool backend. If SANDBOX_DOMAIN
is not set, builder-written code is run in the same origin that serves your Retool instance.
The domain you use for SANDBOX_DOMAIN
must be a fully functional domain that routes HTTP requests to your Retool instance. In many cases, this requires registering a new domain, as well as configuring its DNS records.
SANDBOX_DOMAIN=https://not-your-primary-domain.com
SERVICE_TYPE
Used to set the Retool services a container runs. Separate multiple values with commas with no spaces. If no SERVICE_TYPE
is specified, all services are run.
Acceptable values
MAIN_BACKEND
JOBS_RUNNER
DB_CONNECTOR
DB_SSH_CONNECTOR
WORKFLOW_BACKEND
WORKFLOW_TEMPORAL_WORKER
SERVICE_TYPE=MAIN_BACKEND,JOBS_RUNNER
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 with OIDC 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 with OIDC 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 your OpenID Provider returns a refresh token in the initial login flow, Retool automatically uses it to refresh the access and ID tokens every two hours by default. 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
Returns 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
Roles set using this environment variable are case sensitive. This means:
- Roles set within your IdP that you pass within the variable need to match exactly. For example, if you have a
Retool Admin
role in your IdP, you need to passRetool Admin
. - Roles within Retool are always lowercase. For example, if you have a
Retool Admin
role within your IdP, and you want to map it to Retool'sadmin
role, you need to set it usingRetool Admin → admin
.
CUSTOM_OAUTH2_SSO_ROLE_MAPPING_DISABLED
Disables the mapping of roles from your OpenID provider to Retool permission groups. You need to set this variable to true
to disable passing roles from JWTs.
CUSTOM_OAUTH2_SSO_ROLE_MAPPING_DISABLED=true
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
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
LDAP_ROLE_MAPPING
The mapping of Google LDAP Groups or SAML groups to Retool permission groups used for Google Group syncing and SAML role mapping.
LDAP_ROLE_MAPPING="retool-admins -> admin, support -> Support"
Roles set using this environment variable are case sensitive. This means:
- Roles set within your IdP that you pass within the variable need to match exactly. For example, if you have a
Retool Admin
role in your IdP, you need to passRetool Admin
. - Roles within Retool are always lowercase. For example, if you have a
Retool Admin
role within your IdP, and you want to map it to Retool'sadmin
role, you need to set it usingRetool Admin → admin
.
LDAP_ROLE_MAPPING_DISABLED
Disable syncing SAML groups or Google Groups to Retool permission groups. When LDAP_ROLE_MAPPING
is set and LDAP_ROLE_MAPPING_DISABLED
is true
, Retool logs the groups that would have synced to Retool when a user logs in.
LDAP_ROLE_MAPPING_DISABLED=true
LDAP_SYNC_ALL_GROUPS
Whether to sync all groups regardless of whether they're configured in the LDAP_ROLE_MAPPING
environment variable. When enabled, new groups are created during SAML sync.
LDAP_SYNC_ALL_GROUPS=true
LDAP_SYNC_GROUP_CLAIMS
Enable syncing Google Groups to Retool.
LDAP_SYNC_GROUP_CLAIMS=true
LDAP_SERVER_URL
When syncing Google Groups to Retool, the LDAP server URL for Google's Secure LDAP Service.
LDAP_SERVER_URL="ldaps://ldap.google.com:636"
LDAP_SERVER_NAME
When syncing Google Groups to Retool, the LDAP server name.
LDAP_SERVER_NAME="ldap.google.com"
LDAP_BASE_DOMAIN_COMPONENTS
When syncing Google Groups to Retool, the organization's email domain in DC syntax.
LDAP_BASE_DOMAIN_COMPONENTS="dc=example,dc=com"
LDAP_SERVER_CERTIFICATE
When syncing Google Groups to Retool, the certificate from the downloaded bundle.
LDAP_SERVER_CERTIFICATE=filename