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`
`AI_SIDEKICK`	(Mage Pro only.) Controls AI Sidekick, which defaults to enabled when this variable is unset. Set it to `0` to hide AI chat entry points and reject Sidekick backend requests, including runtime runs, model and proxy session tokens, and voice transcription; set it to `1`, `true`, or `t` (case-insensitive) to enable Sidekick explicitly.	`1` (default), `0`
`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_MAX_RESOURCE_REQUESTS_CPU`	(Mage Pro only.) Maximum CPU request guardrail for K8s executor jobs after env/project/pipeline/block config is merged.	`2000m`
`K8S_EXECUTOR_MAX_RESOURCE_REQUESTS_MEMORY`	(Mage Pro only.) Maximum memory request guardrail for K8s executor jobs after env/project/pipeline/block config is merged.	`4Gi`
`K8S_EXECUTOR_MAX_RESOURCE_LIMITS_CPU`	(Mage Pro only.) Maximum CPU limit guardrail for K8s executor jobs after env/project/pipeline/block config is merged.	`4000m`
`K8S_EXECUTOR_MAX_RESOURCE_LIMITS_MEMORY`	(Mage Pro only.) Maximum memory limit guardrail for K8s executor jobs after env/project/pipeline/block config is merged.	`8Gi`
`K8S_EXECUTOR_DEFAULT_SERVICE_ACCOUNT_NAME`	(Mage Pro only.) Default service account for K8s executor jobs. See K8s executor docs for more details	`default`
`K8S_RESOURCE_USAGE_PROMETHEUS_URL`	(Mage Pro only.) Prometheus base URL for K8s executor resource usage summaries. See Monitoring with Prometheus.	—
`K8S_RESOURCE_USAGE_PROMETHEUS_BEARER_TOKEN`	(Mage Pro only.) Bearer token for Prometheus resource usage queries. Takes precedence over basic auth when set.	—
`K8S_RESOURCE_USAGE_PROMETHEUS_USERNAME`	(Mage Pro only.) Username for Prometheus basic authentication.	—
`K8S_RESOURCE_USAGE_PROMETHEUS_PASSWORD`	(Mage Pro only.) Password for Prometheus basic authentication.	—
`K8S_RESOURCE_USAGE_PROMETHEUS_TIMEOUT_SECONDS`	(Mage Pro only.) Timeout for each Prometheus resource usage query.	`5`
`K8S_RESOURCE_USAGE_PROMETHEUS_STEP_SECONDS`	(Mage Pro only.) Query range step for Prometheus CPU and memory samples.	`15`
`K8S_RESOURCE_USAGE_PROMETHEUS_COMPLETION_DELAY_SECONDS`	(Mage Pro only.) Delay before retrying Prometheus once for completed K8s executor runs with too few samples.	`K8S_RESOURCE_USAGE_PROMETHEUS_STEP_SECONDS`
`K8S_RESOURCE_USAGE_PROMETHEUS_VERIFY_TLS`	(Mage Pro only.) Set to `0`, `false`, `no`, or `off` to skip TLS certificate verification for Prometheus resource usage queries.	`true`
`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.	`1073741824`
`MAGE_CODEX_CHAT_ATTACHMENT_MAX_SESSION_BYTES`	(Mage Pro only.) Maximum total attachment size, in bytes, allowed in one Mage Pro AI Chat session.	`2147483648`
`MAGE_CODEX_CHAT_ARCHIVE_ATTACHMENT_MAX_BYTES`	(Mage Pro only.) Maximum size, in bytes, for one Mage Pro AI Chat browser-zipped folder archive attachment.	`1073741824`
`MAGE_CODEX_CHAT_ARCHIVE_ATTACHMENT_MAX_SESSION_BYTES`	(Mage Pro only.) Maximum total attachment size, in bytes, allowed in one Mage Pro AI Chat session when the new attachment is a browser-zipped folder archive.	`2147483648`
`MAGE_CODEX_CHAT_ATTACHMENT_CONTENT_PREVIEW_BYTES`	(Mage Pro only.) Maximum bytes of text content from one Mage Pro AI Chat attachment that Codex receives in the uploaded-file manifest.	`16384`
`MAGE_CODEX_CHAT_ATTACHMENT_CONTENT_PREVIEW_TOTAL_BYTES`	(Mage Pro only.) Maximum total bytes of text attachment content previews sent to Codex for one chat turn.	`65536`
`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. Leave unset or set to `0` for unlimited.	unset
`MAGE_CODEX_CHAT_MODEL`	(Mage Pro only.) Default model used by Mage Pro AI Chat when a chat request does not override it. Falls back to `MAGE_CODEX_DEFAULT_MODEL` when unset.	`gpt-5.5`
`MAGE_CODEX_CHAT_PROGRESS_HEARTBEAT_SECONDS`	(Mage Pro only.) Seconds between Mage Pro AI Chat progress heartbeat events while the agent is running without a new tool, command, or final-response event.	`1`
`MAGE_CODEX_CHAT_RATE_LIMIT_RETRY_MAX_SECONDS`	(Mage Pro only.) Maximum time Mage Pro AI Chat waits and retries a Codex run after a model rate-limit response before showing the rate-limit error. Set to `0` to disable automatic retry.	`30`
`MAGE_CODEX_CHAT_RATE_LIMIT_RETRY_INITIAL_DELAY_SECONDS`	(Mage Pro only.) Initial delay before retrying a Codex run after a model rate-limit response. Mage increases the delay on later attempts up to `MAGE_CODEX_CHAT_RATE_LIMIT_RETRY_MAX_DELAY_SECONDS`.	`5`
`MAGE_CODEX_CHAT_RATE_LIMIT_RETRY_MAX_DELAY_SECONDS`	(Mage Pro only.) Maximum delay between automatic Codex run retry attempts after a model rate-limit response.	`30`
`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. The AI Chat execution-settings menu takes precedence for that chat. `ultra` is accepted as an alias for Codex CLI’s highest supported value, `xhigh`.	`low`, `medium`, `high`, `xhigh`, `ultra`
`MAGE_CODEX_CHAT_SPEED`	(Mage Pro only.) Default Codex speed used by Mage Pro AI Chat when a chat request does not override it. The AI Chat execution-settings menu takes precedence for that chat.	`standard`, `fast`
`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_DEFAULT_MODEL`	(Mage Pro only.) Default Codex model used by Mage Pro AI Chat and Mage agent MCP sessions when a more specific chat model is not configured. Spawned Codex sessions inherit this value.	`gpt-5.5`
`MAGE_SERVER_MAX_BODY_SIZE`	Maximum HTTP request body size, in bytes, accepted by the Mage Tornado server. When unset, Mage sets this to the larger AI Chat attachment limit plus multipart overhead so large uploads can reach the API resource and return normal JSON errors.	`max(MAGE_CODEX_CHAT_ATTACHMENT_MAX_BYTES, MAGE_CODEX_CHAT_ARCHIVE_ATTACHMENT_MAX_BYTES) + 67108864`
`MAGE_SERVER_MAX_BUFFER_SIZE`	Maximum HTTP request buffer size, in bytes, accepted by the Mage Tornado server. Defaults to `MAGE_SERVER_MAX_BODY_SIZE`.	`MAGE_SERVER_MAX_BODY_SIZE`
`MAGE_SIDEKICK_VOICE_DICTATION_DAILY_MAX_BYTES`	(Mage Pro only.) Maximum daily audio bytes accepted per user before Mage Pro refuses new Sidekick voice dictation proxy requests.	`524288000`
`MAGE_SIDEKICK_VOICE_DICTATION_LANGUAGE`	(Mage Pro only.) Default language code sent with Sidekick voice dictation transcription requests when the browser does not provide one. Invalid values fall back to English.	`en`
`MAGE_SIDEKICK_VOICE_DICTATION_MAX_BYTES`	(Mage Pro only.) Maximum audio upload size Mage Pro accepts and passes into the scoped OpenAI proxy token budget for Sidekick voice dictation.	`26214400`
`MAGE_SIDEKICK_VOICE_DICTATION_MAX_SECONDS`	(Mage Pro only.) Maximum client recording duration Mage Pro exposes to Sidekick and passes into the scoped OpenAI proxy token budget for voice dictation.	`120`
`MAGE_SIDEKICK_VOICE_DICTATION_MODEL`	(Mage Pro only.) Transcription model requested through the Mage Pro API OpenAI proxy for Sidekick voice dictation.	`gpt-4o-transcribe`
`MAGE_SIDEKICK_VOICE_DICTATION_MONTHLY_MAX_BYTES`	(Mage Pro only.) Maximum monthly audio bytes accepted per user before Mage Pro refuses new Sidekick voice dictation proxy requests.	`10737418240`
`MAGE_SIDEKICK_VOICE_DICTATION_PROMPT`	(Mage Pro only.) Prompt sent with Sidekick voice dictation transcription requests. Defaults to preserving Mage, Sidekick, Codex, pipeline, Kubernetes, GitHub, API, and other technical terms, and is capped at 1000 characters.	`Transcribe English voice dictation for Mage AI Sidekick...`
`MAGE_SIDEKICK_VOICE_DICTATION_RATE_LIMIT_PER_MINUTE`	(Mage Pro only.) Maximum Sidekick voice dictation transcription attempts accepted per user per minute before Mage Pro returns a rate-limit response.	`20`
`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.) Server-side Mage Pro API key used when Mage Pro proxy mode or other Mage Pro API integrations call the shared Mage Pro API service. Mage Pro AI Chat does not pass this key to the Codex child process or Mage MCP tool environment.	`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