Environments are sub-divisons of workspaces, allowing you to deploy the same app (or set of apps) in multiple instances for different purposes without changing your code. Typical use cases for environments include having one dev environment and one prod environment, preventing overwriting production apps when developing new features, while still being able to deploy changes to a “live” and potentially complex structure of apps.

Each environment has its own set of Secrets and any object lookups performed from an app in an environment will by default look for objects in the same environment.

By default, every workspace has a single Environment called “main”. New environments can be created on the CLI:

modal environment create dev

(You can run modal environment --help for more info)

Once created, Environments show up as a dropdown menu in the navbar of the Modal dashboard, letting you set browse all Modal Apps and Secrets filtered by which Environment they were deployed to.

Most CLI commands also support an --env flag letting you specify which Environment you intend to interact with, e.g.:

modal run --env=dev app.py
modal nfs create --env=dev storage

Note that if you have multiple Environments in your workspace and try to interact with it without specifying an Environment, an error will be raised.

To set a default Environment for your current CLI profile you can use modal config set-environment, e.g.:

modal config set-environment dev

Alternatively, you can set the MODAL_ENVIRONMENT environment variable.

Environment web suffixes

Environments have a ‘web suffix’ which is used to make web endpoint URLs unique across your workspace. One Environment is allowed to have no suffix ("").

Cross environment lookups

It’s possible to explicitly look up objects from other Environments than your app runs in:

production_secret = modal.Secret.from_name(


However, the environment_name argument is optional and omitting it will use the Environment from the object’s associated app or calling context.