Manage Configuration Variables

Manage configuration variables in Retool.

Available on:Team planBusiness planEnterprise plan

Configuration Variables ("config vars") are environment-specific values and secrets that you can reference in Retool resource configurations, apps, and queries. Variables are encrypted in Retool's Cloud database or if you self-host Retool, in your Retool 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.

You must be an admin to create and edit Configuration Variables. Any user with resource Edit permissions can use secret config vars in connector definitions. Any user with app Edit permissions can access non-secret config vars in apps.

Configuration Variables in 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.

Configuration Variables in apps

You can configure environment-specific Configuration Variables in your apps and queries. Secret Configuration Variables are not available in apps and queries.

note

You cannot use configuration variables in public apps or external apps.

Create Configuration Variables

To create a config var, go to Settings > Configuration Variables.

Config var values are configurable per Retool environment. For example, if you have a db_password config var, you may want the values of the config var to vary across prod, staging, and dev environments.

Secret Configuration Variables

When you create a config var, you can optionally mark the var as Secret. Secret config vars can only be accessed in resource configurations, and their values are never exposed on the frontend.

Config vars that are not marked Secret are accessible across your resources, apps, and queries. Non-secret values can be exposed on the frontend, so they are not recommended for storing sensitive values.

Use Configuration Variables

You can use autocomplete to access config vars in the resource editor and in apps. Config vars then use the correct value for the current environment, as long as the config var is defined for that environment.

Reference config vars using the following syntax.

In the resource editor:

{{ environment.variables.YOUR_VAR_NAME }}

In apps and queries:

{{ retoolContext.configVars.YOUR_VAR_NAME }}

warning

Config vars 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 config vars on each instance.

Configuration Variables, environment variables, and Secrets Managers

The use of config vars, RETOOL_EXPOSED variables, and Secrets Manager depends on your security and permissioning 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 config vars 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.