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 specific to resource environments and can be either values or secrets.
Retool encrypts configuration variables on cloud instances or, if you self-host Retool, in your deployment's PostgreSQL storage database.
Requirements
Configuration variables are available to cloud instances and self-hosted instances using versions 3.4.0 and later for organizations on a Business or an Enterprise plan. Configuration variables in workflows are currently available to cloud instances
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 resource environment-specific values. For example, if you create a db_password configuration variable, you may need to specify different values depending on the resource environment (e.g., production or staging).
Default values
You can set a default value for a configuration variable that applies to all environments without an explicit value. This is useful when you want to:
- Use the same value across most environments and only override specific ones.
- Ensure all environments have a fallback value.
To set a default value, enter a value in the Default Value field when creating or editing a configuration variable. You can create a configuration variable with only a default value, or combine a default value with environment-specific values.
When an environment has both a default value and an environment-specific value configured, the environment-specific value takes precedence. Environments without their own explicit value display (using default value) as placeholder text.
On the main Configuration variables page:
- Variables with only a default value show All Environments in the Environment column.
- Variables with both a default value and environment-specific values show All Other Environments for the default value row.
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, , and workflow IDE. Retool uses the appropriate value depending on the current resource 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, and are stored encrypted. Use configuration variables when you need to access variables per resource environment.
On self-hosted Retool instances, 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 with a cloud instances or self-hosted instance on version 3.42 and later can use the Retool API to manage configuration variables.