Modal intentionally keeps configurability to a minimum.

The main configuration options are the API tokens: the token id and the token secret. These can be configured in two ways:

  1. By running the modal token set command. This writes the tokens to .modal.toml file in your home directory.
  2. By setting the environment variables MODAL_TOKEN_ID and MODAL_TOKEN_SECRET. This takes precedence over the previous method.


The .modal.toml file is generally stored in your home directory. It should look like this::

token_id = "ak-12345..."
token_secret = "as-12345..."

You can create this file manually, or you can run the modal token set ... command (see below).

Setting tokens using the CLI

You can set a token by running the command::

modal token set \
  --token-id <token id> \
  --token-secret <token secret>

This will write the token id and secret to .modal.toml.

If the token id or secret is provided as the string - (a single dash), then it will be read in a secret way from stdin instead.

Other configuration options

Other possible configuration options are:

  • loglevel (in the .toml file) / MODAL_LOGLEVEL (as an env var). Defaults to WARNING. Set this to DEBUG to see internal messages.
  • logs_timeout (in the .toml file) / MODAL_LOGS_TIMEOUT (as an env var). Defaults to 10. Number of seconds to wait for logs to drain when closing the session, before giving up.
  • automount (in the .toml file) / MODAL_AUTOMOUNT (as an env var). Defaults to True. By default, Modal automatically mounts modules imported in the current scope, that are deemed to be “local”. This can be turned off by setting this to False.
  • traceback (in the .toml file) / MODAL_TRACEBACK (as an env var). Defaults to False. Enables printing full tracebacks on unexpected CLI errors, which can be useful for debugging client issues.


Some “meta-options” are set using environment variables only:

  • MODAL_CONFIG_PATH lets you override the location of the .toml file, by default ~/.modal.toml.
  • MODAL_PROFILE lets you use multiple sections in the .toml file and switch between them. It defaults to “default”.


class Config(object)

Singleton that holds configuration used by Modal internally.

def __init__(self):


def get(self, key, profile=None, use_env=True):

Looks up a configuration value.

Will check (in decreasing order of priority):

  1. Any environment variable of the form MODAL_FOO_BAR (when use_env is True)
  2. Settings in the user’s .toml configuration file
  3. The default value of the setting


def override_locally(self, key: str, value: str):
    # Override setting in this process by overriding environment variable for the setting
    # Does NOT write back to settings file etc.


def to_dict(self):


def config_profiles():

List the available modal profiles in the .modal.toml file.


def config_set_active_profile(env: str) -> None:

Set the user’s active modal profile by writing it to the .modal.toml file.