Skip to main content

Configure environments

Learn how to create and use multiple environments for production and testing.

All Retool organizations on paid plans have production and staging environments:

  • Production is the default environment for Retool apps and cannot be removed or renamed.
  • Staging allows you to test apps without impacting production.

Administrators of Retool Cloud or self-hosted Retool organizations can create any number of separate environments to build, run, and test apps. All administrators and editors.mdx#configure-access-rules-for-a-permission-group) can access and use these environments.

When you configure a resource, you set the environments that resource is accessible in. This allows you to test apps with staging data and restrict access to production data. Environments differ from versioning apps: apps function across environments. When you query a resource in an app, the resource's environments determine the data the app uses.

Create an environment​

Administrators create and manage environments for a Retool organization from the Environments settings. Click Create new to create an environment. All environment must have a unique name and display color.

Creating a new environment

Configure environment resources​

Multiple environments allow you to display and test against nonsensitive (non-production) data. You can set up connections to your data sources (e.g., database or API) and add environment-specific credentials within the same resource.

Each resource must be configured for your organization's default environment. New resources are configured for the default environment automatically.

To configure a resource for a specific environment:

  1. Select the Resources tab and click Edit.
  2. Add the appropriate resource credentials for each defined environment.

You don't need to configure a resource for every environment. Keep in mind that you cannot switch to an environment while editing an app if it hasn't been configured with a resource that is referenced by the app.

Configuring environment resources

Configure permissions​

Resource environment permissions are available on self-hosted Retool versions 3.18 and later, and Cloud versions 3.21 and later for organizations on the Enterprise plan.

These versions introduced a Use permission for resources that allows users to run queries against the resource. This behaviour is equivalent to the Edit permission in previous releases.

Admins can configure different access levels to environment resources from Settings > Permissions. Learn more in the permission groups documentation.

Switch environments​

You can switch between environments configured with resources directly from the App IDE. Users with edit or admin access can also switch environments in preview mode. You cannot switch to an environment that is not configured with a required resource.

You can access resource settings and configure them for other environments by clicking Edit in the Resource field of a query.

Switching environments automatically reloads the app to use the appropriate resources and credentials. If your resource requires authentication, users must re-authenticate the first time they switch to a different environment. Retool then stores separate access tokens for each environment.

Use specific environments across apps​

Retool saves your most recently selected environment to your browser cache and automatically uses it the next time you open an app. For example, if you switch to a staging environment in one app, the next app you open automatically uses the same staging environment.

You can link directly to a Retool app and include the _environment URL query parameter to automatically open it with a specified environment.

The default environment for Public Apps is production.

Reference the selected environment​

The retoolContext object contains the environment property that corresponds to the name of the environment currently in use. Use {{ retoolContext.environment }} to reference this anywhere you need to surface the environment in your app.