Using multiple environments

If you're on a paid plan, your Retool organization is initially set up with 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.


Environments are only available on paid Retool plans.

Administrators of Retool organizations on Cloud or with an on-premise deployment of Retool Self-hosted v2.87+ can create any number of separate environments to build, run, and test apps. All administrators and editors can access and use these environments.

Create a new environment

Administrators create and manage environments using the Environments settings for your Retool organization:

  1. Log in to your Retool organization.
  2. Open the User menu on the upper-right.
  3. Click Settings.
  4. Select the Environments tab on the left.

Click Create new to create a new environment. All environment must have a unique name and display color.

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.

Switch environments

You can switch between environments that are configured with resources directly from the App editor. 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.

Here, the [dev] internal_retool (readonly) resource is only configured for the production environment, so you can't toggle to other environments until you provide appropriate configurations.

You can quickly access resource settings and configure them for other environments by clicking Edit resource in the bottom panel.

Switching environments automatically reloads the app to use the appropriate resources and credentials.

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.