Manage configuration variables
Learn how to create configuration variables and reference them across Retool.
| Configuration Variables Availability | |||
|---|---|---|---|
| Cloud | Generally Available | ||
| Self-hosted Edge 3.36 or later | Generally Available | ||
| Self-hosted Stable 3.33 or later | Generally Available | ||
You can specify configuration variables for reference in resource configurations, apps, and workflows. Configuration variables are environment-specific and can be either values or secrets.
Retool encrypts configuration variables on Retool Cloud or, if you self-host Retool, in your deployment's PostgreSQL storage database.
Requirements
Configuration variables are available on Retool Cloud and self-hosted Retool versions 3.4.0 and later for organizations on the Team, Business, and Enterprise plans. Configuration variables in workflows are currently available on Retool Cloud.
You must be an admin to create and edit configuration variables. Configuration variable values and secrets availability depends on usage. Only users with Edit permissions for a relevant area (e.g., resources) can use configuration variables.
| Name | Values | Secrets | Description |
|---|---|---|---|
| Resources | Configuring resources in Retool can require handling sensitive values, e.g. database passwords or API keys. Retool is SOC 2 Type 2 compliant, and most customers store these values with Retool. Configuration variables allow you to centralize and control access to these values. If you have specific security requirements that require you to store secret values externally, rather than encrypted in Retool’s database, consider integrating Retool with a Secrets Manager. | ||
| Apps | Secret configuration variables are not available in apps and queries. You cannot use configuration variable values in public or external apps. | ||
| Workflows | As you build a workflow, Retool sanitizes secret configuration variables in block responses when running individual blocks. Secret values can only be passed to subsequent blocks when the workflow is run in its entirety, either by clicking Run workflow in the Workflow IDE or when the workflow is triggered. |
Create configuration variables
To create a configuration variable, go to Settings > Configuration variables.
Configuration variables have environment-specific values. For example, if you create a db_password configuration variable, you may need to specify different values depending on the environment (e.g., production or staging).
Secret configuration variables
To create a secret, toggle Mark variable as secret when creating a configuration variable. Secret configuration variables are available for use only in resource configurations and workflows, and their values are never exposed on the frontend. Use secrets if you need to store sensitive information, such as security credentials.
Use configuration variables
You can use autocomplete to access configuration variables in the resource editor, App IDE, and Workflow IDE. Retool uses the appropriate value depending on the current environment.
Reference configuration variables in resource configurations using the following syntax.
{{ environment.variables.YOUR_VAR_NAME }}
In apps, workflows, and queries:
{{ retoolContext.configVars.YOUR_VAR_NAME }}
Configuration variables are cached so it may take up to five minutes for your changes to take effect.
Configuration variables with multi-instance deployments
Config vars are recommended for use with Protected Resources. When protecting a resource, only the template value ({{ environment.variables.your_name }}) is stored in Source Control. You must define your configuration variables on each instance.
Configuration variables, environment variables, and Secrets Managers
The use of configuration variables, RETOOL_EXPOSED variables, and Secrets Manager depends on your security and permission requirements.
Config vars are set directly in the Retool settings web interface, are available on Retool Cloud and self-hosted Retool, and are stored encrypted. Use configuration variables when you need to access variables per environment.
On self-hosted Retool deployments, RETOOL_EXPOSED_* variables are set per-instance as environment variables. Their values are never exposed in Retool.
If your use case requires higher levels of security, integrating with a third-party Secrets Manager such as AWS or Vault is recommended.
Configuration variables API
Organizations on the Enterprise plan running on Retool Cloud or self-hosted Retool versions 3.42 and later can use the Retool API to manage configuration variables.