Mage 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 or secrets. If you’re running Mage using Docker, you must add the following command line flags:

-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:

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
`ALLOW_DOWNLOADS_OUTSIDE_PROJECT`	Allow signed file downloads for files outside the current project directory.	`0`, `1`
`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
`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 · Helm	—
`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 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 · Helm	—
`WORKSPACE_DEFAULT_RESOURCE_REQUESTS_CPU`	(Mage Pro only.) Default CPU request for workspace containers (when not specified in container_config). See Workspaces docs	`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	1
`DISABLE_TERMINAL`	Setting this variable will disable access to the terminal.	1
`DYNAMIC_BLOCKS_MAX_CHILD_BLOCKS`	Maximum number of dynamic child block runs a dynamic block may create in one expansion. Leave unset or set to `0` to allow unlimited child runs.	`1000`
`DYNAMIC_BLOCKS_MAX_CHILD_BLOCKS_BEHAVIOR`	Behavior when a dynamic block exceeds `DYNAMIC_BLOCKS_MAX_CHILD_BLOCKS`. Use `fail` to stop the run or `limit` to create only up to the configured maximum.	`fail`, `limit`
`DYNAMIC_BLOCKS_MAX_CONCURRENT_CHILD_BLOCKS`	Maximum number of dynamic child block runs that may be queued or running at the same time for one pipeline run. Leave unset or set to `0` to allow unlimited concurrent dynamic child runs.	`25`
`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	See link
`GIT_REPO_PATH`	More information	See link
`GIT_USERNAME`	More information	See link
`GIT_EMAIL`	More information	See link
`GIT_AUTH_TYPE`	More information	See link
`GIT_BRANCH`	More information	See link
`GIT_SYNC_ON_PIPELINE_RUN`	More information	See link
`GIT_SYNC_ON_START`	More information	See link
`GIT_SSH_PUBLIC_KEY`	More information	See link
`GIT_SSH_PRIVATE_KEY`	More information	See link
`GIT_ACCESS_TOKEN`	More information	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	See link
`LDAP_SERVER`	More information	See link
`LDAP_BIND_DN`	More information	See link
`LDAP_BIND_PASSWORD`	More information	See link
`LDAP_BASE_DN`	More information	See link
`LDAP_AUTHENTICATION_FILTER`	More information	See link
`LDAP_AUTHORIZATION_FILTER`	More information	See link
`LDAP_GROUP_FIELD`	More information	See link
`LDAP_ROLES_MAPPING`	More information	See link
`LDAP_DEFAULT_ACCESS`	More information	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	See link
`MAGE_BASE_PATH`	The base path or prefix of the Mage server url. More information	`base/path`
`MAGE_REQUESTS_BASE_PATH`	More information	`base/path`
`MAGE_ROUTESBASE_PATH`	More information	`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_CODEX_CHAT_ATTACHMENT_MAX_BYTES`	(Mage Pro only.) Maximum size, in bytes, for one Mage Pro AI Chat attachment.	`10485760`
`MAGE_CODEX_CHAT_ATTACHMENT_MAX_COUNT`	(Mage Pro only.) Maximum number of attachments allowed in one Mage Pro AI Chat session.	`20`
`MAGE_CODEX_CHAT_ATTACHMENT_MAX_SESSION_BYTES`	(Mage Pro only.) Maximum total attachment size, in bytes, allowed in one Mage Pro AI Chat session.	`52428800`
`MAGE_CODEX_CHAT_MAGE_API_KEY`	(Mage Pro only.) API key the Mage Pro AI Chat runner passes to Mage agent calls back into the current Mage API. Falls back to `MAGE_AGENT_CODEX_API_KEY` or `MAGE_API_KEY`.	`your_api_key`
`MAGE_CODEX_CHAT_MAGE_API_KEY_SECRET`	(Mage Pro only.) Optional Mage secret name that stores the API key for AI Chat runner callbacks into the current Mage API. No secret name is used by default.	`MAGE_AGENT_API_KEY`
`MAGE_CODEX_CHAT_MAGE_API_URL`	(Mage Pro only.) Base Mage API URL the Mage Pro AI Chat runner gives to the Mage agent MCP server. Falls back to `MAGE_CODEX_CHAT_CLUSTER_URL`, local server settings, or the cluster URL.	`https://your-mage-url`
`MAGE_CODEX_CHAT_MAX_CONCURRENT_RUNS`	(Mage Pro only.) Maximum number of Codex chat turns that can run at the same time in one Mage process. Unset, empty, invalid, or non-positive values mean unlimited.	`0` (unlimited), `4`
`MAGE_CODEX_CHAT_MODEL`	(Mage Pro only.) Default model used by Mage Pro AI Chat when a chat request does not override it.	`gpt-5.5`
`MAGE_CODEX_CHAT_OPENAI_API_KEY`	(Mage Pro only.) OpenAI or Codex API key used by Mage Pro AI Chat direct model authentication. `OPENAI_API_KEY` is also accepted as a fallback.	`your_openai_api_key`
`MAGE_CODEX_CHAT_OPENAI_API_KEY_SECRET`	(Mage Pro only.) Mage secret name that stores the API key for Mage Pro AI Chat direct model authentication.	`OPENAI_API_KEY`
`MAGE_CODEX_CHAT_REASONING_EFFORT`	(Mage Pro only.) Default reasoning effort used by Mage Pro AI Chat when a chat request does not override it.	`low`, `medium`, `high`, `xhigh`
`MAGE_CODEX_CHAT_SERVICE_TIER`	(Mage Pro only.) Default service tier used by Mage Pro AI Chat when a chat request does not override it.	`priority`
`MAGE_CODEX_MODEL_AUTH_MODE`	(Mage Pro only.) Select direct API-key authentication or Mage Pro proxy authentication for the AI Chat Codex model provider.	`direct`, `proxy`
`MAGE_CODEX_MODEL_PROXY_BASE_URL`	(Mage Pro only.) OpenAI-compatible proxy base URL used when `MAGE_CODEX_MODEL_AUTH_MODE=proxy`. Defaults from the Mage Pro API endpoint when available.	`https://pro-api.mage.ai/api/v1/codex/openai/v1`
`MAGE_DATABASE_CONNECTION_URL`	Specify the database connection url for orchestration DB. Defaults to local sqlite db.	Example
`MAGE_DATABASE_APPLICATION_NAME`	Override the PostgreSQL `application_name` used by Mage DB connections. Defaults to a generated `mage:<cluster or project>:<hostname>` value.	`mage:production:server-1`
`MAGE_DATABASE_IDLE_IN_TRANSACTION_SESSION_TIMEOUT_MS`	PostgreSQL session timeout, in milliseconds, for idle transactions opened by Mage. Set to `0` to disable the per-session timeout.	`120000`
`MAGE_DATABASE_LOCK_TIMEOUT_MS`	Optional PostgreSQL per-session lock wait timeout, in milliseconds, for Mage DB connections. `0` disables this setting.	`0`
`MAGE_DATABASE_MAX_OVERFLOW`	Extra PostgreSQL connections a Mage process may open above `MAGE_DATABASE_POOL_SIZE`.	`2`
`MAGE_DATABASE_POOL_RECYCLE`	Number of seconds before SQLAlchemy recycles an idle PostgreSQL pooled connection.	`1800`
`MAGE_DATABASE_POOL_SIZE`	Base SQLAlchemy connection pool size per Mage process for PostgreSQL orchestration DB connections. Use small values for shared workspaces.	`5`
`MAGE_DATABASE_POOL_TIMEOUT`	Number of seconds a Mage request waits for a PostgreSQL pooled connection before failing with a pool exhaustion error.	`10`
`MAGE_DATABASE_STATEMENT_TIMEOUT_MS`	Optional PostgreSQL per-session statement timeout, in milliseconds, for Mage DB connections. `0` disables this setting.	`0`
`MAGE_PRO_API_API_KEY`	(Mage Pro only.) Mage Pro API key used when Mage Pro proxy mode or other Mage Pro API integrations call the shared Mage Pro API service.	`your_mage_pro_api_key`
`MAGE_PRO_API_ENDPOINT`	(Mage Pro only.) Mage Pro API host used by Mage Pro proxy mode and other Mage Pro API integrations. Do not include the URL scheme. Hosted production clusters use `pro-api.mage.ai`; staging hosts such as `pro-api-staging.mage.ai` are for non-production environments.	`pro-api.mage.ai`
`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`	(Mage Pro only.) 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	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	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`

Adventure starts here

Concepts

Project

Contributing

About

Mage environment variables

Environment variables in Mage Pro

Adding or modifying environment variables:

Environment variables in Mage OSS

Setting the prefix for Mage URL

Default variables

​Environment variables in Mage Pro

​Adding or modifying environment variables:

​Environment variables in Mage OSS

​Setting the prefix for Mage URL

​Default variables

Environment variables in Mage Pro

Adding or modifying environment variables:

Environment variables in Mage OSS

Setting the prefix for Mage URL

Default variables