> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mage.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Mage environment variables
> Configure Mage settings through environment variables.
## Environment variables in Mage Pro
Environment variables are set from the Mage Pro cluster management portal. Check out the steps and video below on how to create environment variables.
### Adding or modifying environment variables:
* Click the "Edit / add variables" button
* On the Environment Variables screen, you can either input a value directly or add a custom environment variable by specifying its key-value pair
* Click "Save changes" to update the settings.
After clicking the "Save changes" button the cluster will automatically restart.
## Environment variables in Mage OSS
Environment variables may be set in your Docker container to configure Mage settings. If you’re running Mage using `pip` or `conda`, your local machine’s environment variables
are accessible within the running Mage app.
Environment variables are different from [runtime variables](/getting-started/runtime-variable) or [secrets](/development/variables/secrets).
If you’re running Mage using Docker, you must add the following command line flags:
```bash theme={"system"}
-e SOME_VARIABLE_NAME_1=secret_value_1 -e SOME_VARIABLE_NAME_2=secret_value_2
```
The command to run Mage using Docker could look like this:
```bash theme={"system"}
docker run -it -p 6789:6789 -v $(pwd):/home/src \
-e SOME_VARIABLE_NAME_1=secret_value_1 -e SOME_VARIABLE_NAME_2=secret_value_2 \
mageai/mageai /app/run_app.sh mage start [project_name]
```
## Setting the prefix for Mage URL
You may need to add a prefix to the Mage url. You can configure the Mage server to start
at a prefix to the url by setting the `MAGE_BASE_PATH` environment variable.
Make sure to set the base path without the leading slash. For example, if you want to start Mage at
`http://localhost:6789/base/url/path`, you would configure your environment
variable like this:
`export MAGE_BASE_PATH=base/url/path`
You can also configure the base path separately for client requests and backend routes by setting
the `MAGE_REQUESTS_BASE_PATH` and `MAGE_ROUTES_BASE_PATH` environment variables respectively.
| | |
| ------------------------- | ----------------------------------------------------------------------------------- |
| `MAGE_BASE_PATH` | Set base path for the entire app. |
| `MAGE_REQUESTS_BASE_PATH` | Set base path for frontend requests and urls, defaults to value of `MAGE_BASE_PATH` |
| `MAGE_ROUTES_BASE_PATH` | Set base path for backend routes, defaults to value of `MAGE_BASE_PATH` |
## Default variables
These are the environment variables used in Mage.
| Variable name | Description | Example values |
| --------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `ACTIVE_DIRECTORY_DIRECTORY_ID` | Set this value to your organization's tenant id to enable signing in with Microsoft account. | [More info](/production/authentication/microsoft) |
| `AUTHENTICATION_MODE` | Set the authentication mode in Mage. Omitting the variable will default to basic password authentication. | `ldap` |
| `DATAFRAME_SAMPLE_COUNT_PREVIEW` | Number of lines to display in block sample output preview for dataframes. Not suggested to go over 10 lines (defaults to 10). | 5 |
| `DEBUG` | Turn on "debug" mode. Mage will output more logs that could be useful for debugging issues. | 1 |
| `DEFAULT_EXECUTOR_TYPE` | The default executor type to run blocks | See enum types [here](https://docs.mage.ai/production/configuring-production-settings/compute-resource#2-set-executor-type-and-customize-the-compute-resource-of-the-mage-executor) |
| `K8S_DEFAULT_CONFIG_PATH` | **(Mage Pro only.)** Path to YAML file for default K8s executor config; merged with block/project config. Prefer configuring via Helm `k8sExecutorConfig`. [K8s executor](/production/executors/k8#default-config-file) · [Helm](/production/deploying-to-cloud/using-helm#default-workspace-and-k8s-executor-config) | — |
| `K8S_EXECUTOR_DEFAULT_RESOURCE_REQUESTS_CPU` | **(Mage Pro only.)** Default CPU request for K8s executor jobs (when not specified in config) | `250m` |
| `K8S_EXECUTOR_DEFAULT_RESOURCE_REQUESTS_MEMORY` | **(Mage Pro only.)** Default memory request for K8s executor jobs (when not specified in config) | `512Mi` |
| `K8S_EXECUTOR_DEFAULT_RESOURCE_LIMITS_CPU` | **(Mage Pro only.)** Default CPU limit for K8s executor jobs (when not specified in config) | `500m` |
| `K8S_EXECUTOR_DEFAULT_RESOURCE_LIMITS_MEMORY` | **(Mage Pro only.)** Default memory limit for K8s executor jobs (when not specified in config) | `1Gi` |
| `K8S_EXECUTOR_DEFAULT_SERVICE_ACCOUNT_NAME` | **(Mage Pro only.)** Default service account for K8s executor jobs. See [K8s executor docs](/production/executors/k8#environment-variables-reference) for more details | `default` |
| `WORKSPACE_DEFAULT_CONFIG_PATH` | **(Mage Pro only.)** Path to YAML file for default workspace config; merged with user config. Prefer configuring via Helm `workspaceConfig`. [Workspaces](/guides/developer-ux/workspaces#default-workspace-config-file) · [Helm](/production/deploying-to-cloud/using-helm#default-workspace-and-k8s-executor-config) | — |
| `WORKSPACE_DEFAULT_RESOURCE_REQUESTS_CPU` | **(Mage Pro only.)** Default CPU request for workspace containers (when not specified in container\_config). See [Workspaces docs](/guides/developer-ux/workspaces#default-resource-configuration) | `500m` |
| `WORKSPACE_DEFAULT_RESOURCE_REQUESTS_MEMORY` | **(Mage Pro only.)** Default memory request for workspace containers (when not specified in container\_config) | `2Gi` |
| `WORKSPACE_DEFAULT_RESOURCE_LIMITS_CPU` | **(Mage Pro only.)** Default CPU limit for workspace containers (when not specified in container\_config) | `4` |
| `WORKSPACE_DEFAULT_RESOURCE_LIMITS_MEMORY` | **(Mage Pro only.)** Default memory limit for workspace containers (when not specified in container\_config) | `8Gi` |
| `DISABLE_NOTEBOOK_EDIT_ACCESS` | Setting this variable will disable edit access based on the value. [More information](/production/configuring-production-settings/overview#read-only-access) | 1 |
| `DISABLE_TERMINAL` | Setting this variable will disable access to the terminal. | 1 |
| `ENV` | Set the environment of the Mage app. You can use different code or configurations in different environments. | `dev`, `staging`, `production`/`prod`, `test` |
| `GIT_REPO_LINK` | [More information](/production/data-sync/git-sync#git-sync-settings-as-environment-variables) | See link |
| `GIT_REPO_PATH` | [More information](/production/data-sync/git-sync#git-sync-settings-as-environment-variables) | See link |
| `GIT_USERNAME` | [More information](/production/data-sync/git-sync#git-sync-settings-as-environment-variables) | See link |
| `GIT_EMAIL` | [More information](/production/data-sync/git-sync#git-sync-settings-as-environment-variables) | See link |
| `GIT_AUTH_TYPE` | [More information](/production/data-sync/git-sync#git-sync-settings-as-environment-variables) | See link |
| `GIT_BRANCH` | [More information](/production/data-sync/git-sync#git-sync-settings-as-environment-variables) | See link |
| `GIT_SYNC_ON_PIPELINE_RUN` | [More information](/production/data-sync/git-sync#git-sync-settings-as-environment-variables) | See link |
| `GIT_SYNC_ON_START` | [More information](/production/data-sync/git-sync#git-sync-settings-as-environment-variables) | See link |
| `GIT_SSH_PUBLIC_KEY` | [More information](/production/data-sync/git-sync#git-sync-settings-as-environment-variables) | See link |
| `GIT_SSH_PRIVATE_KEY` | [More information](/production/data-sync/git-sync#git-sync-settings-as-environment-variables) | See link |
| `GIT_ACCESS_TOKEN` | [More information](/production/data-sync/git-sync#git-sync-settings-as-environment-variables) | See link |
| `HIDE_ENV_VAR_VALUES` | Filter out environment variables in notebook output. | 1 |
| `JUPYTER_KERNEL_IDLE_TIMEOUT_SECONDS` | **(Mage Pro only.)** Number of seconds an inactive per-user Jupyter kernel can stay alive after its websocket clients disconnect. Used when `MULTI_USER_JUPYTER_KERNELS=1`. | `1800` |
| `JUPYTER_KERNEL_MAX_PER_SERVER` | **(Mage Pro only.)** Maximum number of per-user Jupyter kernels to keep on one Mage server. When the limit is reached, Mage evicts idle kernels first. Used when `MULTI_USER_JUPYTER_KERNELS=1`. | `50` |
| `JWT_SECRET` | Modify the json web token secret used for encoding and decoding access tokens. Defaults to `materia`. | `your_jwt_secret` |
| `JWT_DOWNLOAD_SECRET` | Modify the json web token secret used for encoding and decoding download tokens. Defaults to randomly generated string value. Use an explicit value in horizontally scalable deployments, e.g.: kubernetes, cloud deployments | `your_jwt_secret` |
| `LDAP_ADMIN_USERNAME` | [More information](/production/authentication/overview#ldap) | See link |
| `LDAP_SERVER` | [More information](/production/authentication/overview#ldap) | See link |
| `LDAP_BIND_DN` | [More information](/production/authentication/overview#ldap) | See link |
| `LDAP_BIND_PASSWORD` | [More information](/production/authentication/overview#ldap) | See link |
| `LDAP_BASE_DN` | [More information](/production/authentication/overview#ldap) | See link |
| `LDAP_AUTHENTICATION_FILTER` | [More information](/production/authentication/overview#ldap) | See link |
| `LDAP_AUTHORIZATION_FILTER` | [More information](/production/authentication/overview#ldap) | See link |
| `LDAP_GROUP_FIELD` | [More information](/production/authentication/overview#ldap) | See link |
| `LDAP_ROLES_MAPPING` | [More information](/production/authentication/overview#ldap) | See link |
| `LDAP_DEFAULT_ACCESS` | [More information](/production/authentication/overview#ldap) | See link |
| `LOGS_DIR_PATH` | Override the logs directory path. Default path is the variables\_dir path (e.g. `/home/src/mage_data/`) | `/home/src/logs_dir` |
| `MAGE_ACCESS_TOKEN_EXPIRY_TIME` | [More information](/production/authentication/overview#ldap) | See link |
| `MAGE_BASE_PATH` | The base path or prefix of the Mage server url. [More information](/getting-started/setup#setting-prefix-for-mage-url) | `base/path` |
| `MAGE_REQUESTS_BASE_PATH` | [More information](/getting-started/setup#setting-prefix-for-mage-url) | `base/path` |
| `MAGE_ROUTESBASE_PATH` | [More information](/getting-started/setup#setting-prefix-for-mage-url) | `base/path` |
| `MAGE_CACHE_DIRECTORY` | The directory Mage uses for storing and retrieving temporary data used in the UI. | `/root/.mage_data/default_repo/.cache` |
| `MAGE_DATABASE_CONNECTION_URL` | Specify the database connection url for orchestration DB. Defaults to local sqlite db. | [Example](/production/configuring-production-settings/overview#postgres) |
| `MAGE_PUBLIC_HOST` | The public host url that can be used to access the Mage app. This value will be used in emails or other notifications. | `http://localhost:6789` |
| `MAGE_RESTART_STREAMING_PIPELINES_ON_REQUIREMENTS_CHANGE` | When true, running streaming pipelines are restarted after the project `requirements.txt` changes. | 1 |
| `MAX_PRINT_OUTPUT_LINES` | The max number of `stdout` lines, such as from `print` statements, included in a message from the websocket server. Defaults to `1000`. | `100` |
| `MULTI_USER_JUPYTER_KERNELS` | **(Mage Pro only.)** Enable a separate Python Jupyter kernel for each authenticated user in the pipeline editor so multiple users can run blocks at the same time. | `0` |
| `REQUIRE_USER_AUTHENTICATION` | Enable user authentication in Mage. [More information](/production/authentication/overview) | 1 |
| `RUN_PIPELINE_IN_ONE_PROCESS` | When True, pipelines will run in one process, unless otherwise specified in the settings for a given pipeline. | 1 |
| `SERVER_VERBOSITY` | [More information](/development/observability/logging#server-logging) | See link |
| `SHELL_COMMAND` | Set shell command to use for the Mage terminal. Default command is `bash` for macOS/Unix and `cmd` for Windows. | `bash`, `cmd`, ... |
| `ULIMIT_NO_FILE` | Override the maximum number of open files allowed in Mage processes. | 8192 |
| `USER_CODE_PATH` | Set this path to be `/home/src/{your_project_name}` so that Mage starts your project and installs the packages in requirements.txt when starting the container. | `/home/src/mage_project` |