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 downloads
• allow-popups: Allow pop-ups
• allow-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:

1. 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 pass Retool Admin.
2. 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's admin role, you need to set it using Retool 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:

1. 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 pass Retool Admin.
2. 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's admin role, you need to set it using Retool 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

LDAP_SERVER_KEY

When syncing Google Groups to Retool, the private key from the downloaded bundle.

LDAP_SERVER_KEY=filename

PRESERVE_PASSWORDS_FIRST_GOOGLE_LOGIN

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_IDP_METADATA

An XML document that contains information necessary for configuring SAML-enabled identity or service providers.

<md:EntityDescriptor xmlns:md="urn:desert:names:tc:SAML:2.0:metadata" entityID="http://www.okta.com/your_entity_id">
<md:IDPSSODescriptor WantAuthnRequestsSigned="false" protocolSupportEnumeration="urn:desert:names:tc:SAML:2.0:protocol">
<md:KeyDescriptor use="signing">
<ds:KeyInfo xmlns:ds="http://www.w3.org/2000/09/xmldsig#">
<ds:X509Data>
<ds:X509Certificate>your_certificate</ds:X509Certificate>
</ds:X509Data>
</ds:KeyInfo>
</md:KeyDescriptor>
<md:NameIDFormat>urn:desert:names:tc:SAML:1.1:nameid-format:emailAddress</md:NameIDFormat>
<md:SingleSignOnService Binding="urn:desert:names:tc:SAML:2.0:bindings:HTTP-POST" Location="https://example-98123.okta.com/app/company/jfdu90324f/sso/saml"/>
<md:SingleSignOnService Binding="urn:desert:names:tc:SAML:2.0:bindings:HTTP-Redirect" Location="https://example-98123.okta.com/app/company/your_entity_id/sso/saml"/>
</md:IDPSSODescriptor>
</md:EntityDescriptor>

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

When SAML_SYNC_GROUP_CLAIMS=true, users are removed from any groups that do not have a corresponding IdP group. This includes users assigned to the Admin group. If you enable this setting, test the signin flow with a non-admin or test user.

SCIM_AUTH_TOKEN

A secret token shared with your SSO provider to provision user accounts. If you use Retool Spaces, this token only applies to the admin Space.

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_SOURCE_CONTROL_SYNCING

Disable polling of GitHub and syncing changes from the Source Control repository. This only pauses the syncing process so apps remain protected.

DISABLE_SOURCE_CONTROL_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 worker threads for the db-connector 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.

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

Push notifications

Environment variables to configure push notifications for Retool Mobile.

MOBILE_PUSH_NOTIFIER_API_TOKEN

Your push notification API token that is provided by Retool.

MOBILE_PUSH_NOTIFIER_API_TOKEN=abc123

MOBILE_PUSH_NOTIFIER_HOST

The URL for the push notification service. Set to https://spb8yl7d3j.execute-api.us-west-2.amazonaws.com.

MOBILE_PUSH_NOTIFIER_HOST=https://spb8yl7d3j.execute-api.us-west-2.amazonaws.com

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. You can also set these variables from the Source Control settings page or with the Retool API.

AZURE_REPOS_USER

The admin user or service account for the Azure DevOps organization.

AZURE_REPOS_USER=retool

AZURE_REPOS_PERSONAL_ACCESS_TOKEN

The user's personal access token, under https://dev.azure.com/{AZURE_REPOS_USER}/_usersSettings/tokens.

AZURE_REPOS_PERSONAL_ACCESS_TOKEN=mpoqd2zy7jklzfbhmuzev46vbbcpkeeqminb4wcvwigsrldasdfa

AZURE_REPOS_ORGANIZATION

The name of the Azure DevOps organization.

AZURE_REPOS_ORGANIZATION=my-organization-name

AZURE_REPOS_REPO

The name of the Azure Repos repository.

AZURE_REPOS_REPO=retool

AZURE_REPOS_MAIN_BRANCH

The default branch for the Azure Repos repository.

AZURE_REPOS_MAIN_BRANCH=main

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 use Kubernetes Secrets, you must base64-encode this value twice.

GITHUB_APP_PRIVATE_KEY=...

GITLAB_URL

The base GitLab URL.

Cloud

GITLAB_URL=https://gitlab.com

Self-managed

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

When set to true, 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

This setting does not affect protected resources.

VERSION_CONTROL_LOCKED=true

Storage database

Storage database environment variables available for use with Self-hosted Retool deployments.

DATABASE_MIGRATIONS_TIMEOUT_SECONDS

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

Workflows

Workflow environment variables available for use with Self-hosted Retool deployments. These environment variables specifically can be applied to the api, workflows-worker, and workflows-backend services.

WORKFLOW_BACKEND_HOST

Endpoint specification for all Retool Workflow-related backend requests, such as querying resources, updating workflow status, and storing block results and logs. The value depends on your deployment configuration, but must include a protocol (http:// or https://).

WORKFLOW_BACKEND_HOST=http://workflows-api

CODE_EXECUTOR_INGRESS_DOMAIN

Endpoint specification for code-executor service, which executes arbitrary user-defined JavaScript and Python code with installed custom libraries. The value depends on your deployment configuration, but must include a protocol (http:// or https://).

CODE_EXECUTOR_INGRESS_DOMAIN=http://code-executor:3004

WORKFLOW_TEMPORAL_CLUSTER_FRONTEND_HOST

The host name of the Temporal cluster. If you're using your own Temporal Cloud, your host may look like: foo.bar.tmprl.cloud. This does not need to be set if using Retool-managed Temporal cluster.

WORKFLOW_TEMPORAL_CLUSTER_FRONTEND_HOST=foo.bar.tmprl.cloud

WORKFLOW_TEMPORAL_CLUSTER_FRONTEND_PORT

The port of the Temporal cluster. This does not need to be set if using Retool-managed Temporal cluster. Defaults to 7233.

WORKFLOW_TEMPORAL_CLUSTER_FRONTEND_PORT=7233

WORKFLOW_TEMPORAL_TLS_ENABLED

Enables TLS for the connection to the Temporal cluster. When this variable is set, Retool expects WORKFLOW_TEMPORAL_TLS_KEY and WORKFLOW_TEMPORAL_TLS_CRT to be specified. You must set this to true if you use your own Temporal Cloud. This does not need to be set if using Retool-managed Temporal cluster. Defaults to false.

WORKFLOW_TEMPORAL_TLS_ENABLED=false

WORKFLOW_TEMPORAL_TLS_KEY

Base64 encoded private key for TLS client certification pair. See Temporal documentation for more details. This does not need to be set if using Retool-managed Temporal cluster.

WORKFLOW_TEMPORAL_TLS_CRT

Base64 encoded public certificate (PEM format) for TLS client certification pair. See Temporal documentation for more details. This does not need to be set if using Retool-managed Temporal cluster.

WORKFLOW_TEMPORAL_SERVER_NAME_OVERRIDE

Overrides the target name (SNI) used for TLS host name checking. This can be useful if you have reverse proxy in front of Temporal server and you want to override the SNI to direct traffic to the appropriate backend server based on custom routing rules. Connections can be refused if the provided SNI does not match the expected host. Adding this override should be done with care. See Temporal documentation for more details. This does not need to be set if using Retool-managed Temporal cluster.

WORKFLOW_TEMPORAL_SERVER_ROOT_CA_CRT

Base64 encoded Root CA certificate used by the server (PEM format). See Temporal documentation for more details. This does not need to be set if using Retool-managed Temporal cluster.

WORKFLOW_TEMPORAL_CLUSTER_NAMESPACE

Temporal namespace used by Retool Workflows. Defaults to workflows.

WORKFLOW_TEMPORAL_CLUSTER_NAMESPACE=workflows

TEMPORAL_TASKQUEUE_WORKFLOW

Used by clients connecting to Temporal for all Retool Workflow-related requests (enqueue, query, etc.). This value should match WORKER_TEMPORAL_TASKQUEUE. Defaults to workflows.

TEMPORAL_TASKQUEUE_WORKFLOW=workflows

WORKFLOW_MONITOR_PROCESS_ENABLED

Used to limit the memory and CPUs available to a workflow while running. If enabled, WORKFLOW_MEMORY_LIMIT_MIBS and WORKFLOW_CPU_LIMIT can be set. If the code-executor service is deployed, set this variable there instead. Defaults to false.

WORKFLOW_MONITOR_PROCESS_ENABLED=false

WORKFLOW_MEMORY_LIMIT_MIBS

If WORKFLOW_MONITOR_PROCESS_ENABLED is set to true, this variable governs the memory available to a workflow while running. If the code-executor service is deployed, set this variable there instead. Defaults to 1536 (1.5 GB).

WORKFLOW_MEMORY_LIMIT_MIBS=1536

WORKFLOW_CPU_LIMIT

If WORKFLOW_MONITOR_PROCESS_ENABLED is set to true, this variable governs the CPUs available to a workflow while running. If the code-executor service is deployed, set this variable there instead. Defaults to 8.

WORKFLOW_CPU_LIMIT=8

Worker only

In addition to the variables defined above, the workflows-worker service (SERVICE_TYPE = WORKFLOW_TEMPORAL_WORKER) can set the following environment variables.

WORKFLOW_WORKER_HEALTHCHECK_PORT

The port on which the worker responds to health checks (/api/checkHealth). The default is 3005.

WORKFLOW_WORKER_HEALTHCHECK_PORT=3005

WORKER_TEMPORAL_TASKQUEUE

Used to specify the Temporal queue from which to poll for all Retool Workflow-related workflows (user-defined or internal). This value should match TEMPORAL_TASKQUEUE_WORKFLOW. Defaults to workflows.

WORKER_TEMPORAL_TASKQUEUE=workflows

WORKFLOW_TEMPORAL_CONCURRENT_ACTIVITIES_LIMIT

Advanced setting for tuning workers. See Temporal documentation for more details. Defaults to 10.

WORKFLOW_TEMPORAL_CONCURRENT_ACTIVITIES_LIMIT=10

WORKFLOW_TEMPORAL_CONCURRENT_TASKS_LIMIT

Advanced setting for tuning workers. See Temporal documentation for more details. Defaults to 10.

WORKFLOW_TEMPORAL_CONCURRENT_TASKS_LIMIT=10

WORKFLOW_TEMPORAL_OPENTELEMETRY_COLLECTOR

Available on self-hosted Retool versions 3.33 and later.

Endpoint specification for OpenTelemetry collector for Temporal Worker metrics. The value depends on your deployment configuration.

If it is not set, Retool exposes metrics using a Prometheus Metrics exporter specified in the worker's runtime options:

telemetryOptions: {
  metrics: {
    prometheus: { bindAddress: '0.0.0.0:9090' }
  }
}

Metrics are available for scraping using the /metrics route.

WORKFLOW_TEMPORAL_OPENTELEMETRY_COLLECTOR=http://open-telemetry-collector-opentelemetry-collector:4318

WORKFLOW_TEMPORAL_STICKY_CACHE_SIZE

Advanced setting for tuning workers. See Temporal documentation for more details. Defaults to 200

WORKFLOW_TEMPORAL_STICKY_CACHE_SIZE=200

WORKFLOW_TEMPORAL_WORKER_SHUTDOWN_GRACE_TIME

Advanced setting for tuning workers. See Temporal documentation for more details. Default to 15 minute.

WORKFLOW_TEMPORAL_WORKER_SHUTDOWN_GRACE_TIME='15 minute'

WORKFLOW_TEMPORAL_WORKFLOW_TASK_POLLERS

Advanced setting for tuning workers. See Temporal documentation for more details. Defaults to 10.

WORKFLOW_TEMPORAL_WORKFLOW_TASK_POLLERS=10

WORKFLOW_TEMPORAL_ACTIVITY_TASK_POLLERS

Advanced setting for tuning workers. See Temporal documentation for more details. Defaults to 2.

WORKFLOW_TEMPORAL_ACTIVITY_TASK_POLLERS=2

Code executor service

Code executor environment variables available for use with Self-hosted Retool deployments. You should only set these environment variables on containers running tryretool/code-executor-service images.

NODE_ENV

Should always be set to production.

NODE_ENV=production

NODE_OPTIONS

Used to specify the maximum heap size for the JavaScript v8 engine. Set to --max_old_space_size=1024.

NODE_OPTIONS="--max_old_space_size=1024"

SANDBOX_MOUNT_DIR

Used to configure where files will be mounted into the sandbox. Defaults to /tmp.

SANDBOX_MOUNT_DIR="/tmp"

SANDBOX_MAX_FILE_DESCRIPTORS

Used to configure the amount of file descriptors within a single sandbox. Defaults to 256.

SANDBOX_MAX_FILE_DESCRIPTORS=256

DISABLE_IPTABLES_SECURITY_CONFIGURATION

Available on self-hosted Retool versions 3.33.30 and later.

Used to explicitly disable default security configs for link-local address, which is done by running the following startup commands requiring elevated privileges:

iptables-legacy -A OUTPUT -d 169.254.0.0/16 -m owner --uid-owner retool_user -j DROP
iptables-legacy -A OUTPUT -d 192.168.0.0/16 -m owner --uid-owner retool_user -j DROP

Set to true if privileged access (e.g NET_ADMIN) cannot be given to the container running Code executor service. Defaults to false.

DISABLE_IPTABLES_SECURITY_CONFIGURATION=false

CONTAINER_UNPRIVILEGED_MODE

Available on self-hosted Retool versions 3.33.30+ and later.

Used to run the code executor service in an unprivileged mode, and removes any sandboxing of user code. Defaults to false.

The Code executor service uses nsjail to sandbox code execution. nsjail requires privileged container access. If your deployment framework does not support privileged access, e.g. in a ECS Fargate deployment, set CONTAINER_UNPRIVILEGED_MODE to true. Note: without sandboxing, use of custom JS libraries and custom Python libraries is not allowed.

This environment variable is also used to disable default security configs for link-local address to prevent EC2 metadata leaks, which is done by running the following startup commands that require elevated privileges:

iptables-legacy -A OUTPUT -d 169.254.0.0/16 -m owner --uid-owner retool_user -j DROP
iptables-legacy -A OUTPUT -d 192.168.0.0/16 -m owner --uid-owner retool_user -j DROP

WORKFLOW_MONITOR_PROCESS_ENABLED

Used to limit the memory and CPUs available to a workflow while running. If enabled, WORKFLOW_MEMORY_LIMIT_MBS and WORKFLOW_CPU_LIMIT can be set. Defaults to false.

WORKFLOW_MONITOR_PROCESS_ENABLED=false

WORKFLOW_MEMORY_LIMIT_MBS

If WORKFLOW_MONITOR_PROCESS_ENABLED is set to true, this variable governs the memory available to a workflow while running. Defaults to 2147 (2 GB).

WORKFLOW_MEMORY_LIMIT_MBS=2147

WORKFLOW_CPU_LIMIT

If WORKFLOW_MONITOR_PROCESS_ENABLED is set to true, this variable governs the CPUs available to a workflow while running. Defaults to 1.

WORKFLOW_CPU_LIMIT=1