Environment variables matrix
Environment variables matrix
This page lists the most important environment variables used across the project, grouped by area. The guidance aims to be tenant-first and prescriptive where possible (for example: prefer Managed Identity authentication for the Azure providers; API keys are a fallback only). Do not commit secrets to source control.
Reasoning Engine is opt-in
The Reasoning Engine agents and MCP server are disabled by default. To enable them, set MASTRA_INCLUDE_REASONING_ENGINE=true in your environment. Without this flag the reasoning-engine MCP server will not start and the Reasoning Engine agents will not be registered.
How to use this page
- Use these examples for local
.envfiles and CI variable names. - Managed Identity-first: When an Azure service supports Managed Identity, prefer the _USE_MANAGED_IDENTITY or client-id variables and leave keys blank in source-controlled files.
Quick sample (.env)
# Azure AI Inference
AZURE_INFERENCE_ENDPOINT=https://example-resource.cognitiveservices.azure.com
AZURE_INFERENCE_CHAT_DEPLOYMENT=GPT-5-Chat
AZURE_INFERENCE_CHAT_API_VERSION=2024-12-01-preview
AZURE_FOUNDRY_USE_MANAGED_IDENTITY=true
AZURE_INFERENCE_API_KEY=
# Azure Content Safety
AZURE_CONTENT_SAFETY_ENDPOINT=https://example-cs.cognitiveservices.azure.com
AZURE_CONTENT_SAFETY_USE_MANAGED_IDENTITY=true
AZURE_CONTENT_SAFETY_KEY=
# Azure SQL
AZURE_SQL_SERVER=server.database.windows.net
AZURE_SQL_DATABASE=mastra
AZURE_SQL_USE_MANAGED_IDENTITY=true
AZURE_SQL_MANAGED_IDENTITY_CLIENT_ID=
# Auth / API
AUTH_API_BASE_URL=https://auth.example.com
AUTH_EMAIL=dev@example.com
AUTH_PASSWORD=secret
AUTH_API_KEY=
APIM_GATEWAY_URL=https://example-apim.azure-api.net
ADMIN_PROXY_SHARED_SECRET=
# Mastra runtime
MASTRA_TARGET=all
MASTRA_SKIP_K12_MCP=false
MASTRA_SKIP_ADMIN_MCP=false
MASTRA_SKIP_DOCS_MCP=false
MASTRA_INCLUDE_REASONING_ENGINE=false
MASTRA_TELEMETRY_DISABLED=true
MASTRA_STARTUP_CHECKS=true
MASTRA_STARTUP_CHECKS_STRICT=true
# Reasoning engine
REASONING_DB_STEP_DATA=false
# Azure Storage (SDAC uploads)
AZURE_STORAGE_ACCOUNT_NAME=<storage-account>
AZURE_STORAGE_USE_MANAGED_IDENTITY=true
SDAC_UPLOAD_CONTAINER_NAME=sdac-uploads
SDAC_ARCHIVE_CONTAINER_NAME=sdac-archive
# K12 / MOEOP Internal API
MOEOP_INTERNAL_BASE_URL=https://api-dev-internal.moeop.org
MOEOP_INTERNAL_AUTH_MODE=basic
MOEOP_INTERNAL_USERNAME=
MOEOP_INTERNAL_PASSWORD=
# Search providers
TAVILY_API_KEY=
PERPLEXITY_API_KEY=
# Telemetry
APPLICATIONINSIGHTS_CONNECTION_STRING=
# K12 / TAP test helpers
K12_TEST_SERVER_URL=https://dev.example.com
K12_TEST_SUBSCRIPTION_KEY=
TAP_API_BASE_URL=https://tap.example.com
CSV export: A CSV export of this matrix is available at assets/env-vars.csv.
Matrix (selected variables)
| Variable | Scope | Example / Default | Required? | Notes |
|---|---|---|---|---|
| AZURE_INFERENCE_ENDPOINT | Azure AI Foundry Voice provider | https://<example-resource>.cognitiveservices.azure.com | Optional | Used by the voice provider (azure-ai-foundry/voice.ts). The main inference provider reads its endpoint from Core.LLMModelCapabilities in the DB — this env var is not used for standard LLM calls. If you include a trailing /openai, the provider strips it. |
| AZURE_INFERENCE_CHAT_DEPLOYMENT | Azure AI Inference provider | GPT-5-Chat | Optional | Fallback deployment name for components not yet using DB capability resolution. Prefer setting DeploymentName in Core.LLMModelCapabilities. |
| AZURE_INFERENCE_CHAT_API_VERSION | Azure AI Inference provider | 2024-12-01-preview | Optional | API version used when interacting with chat surfaces that require it. |
| AZURE_FOUNDRY_USE_MANAGED_IDENTITY | Azure AI Inference provider | true (recommended) | No | When true the provider uses DefaultAzureCredential / Managed Identity. Set to false only to allow key-based fallbacks. |
| AZURE_INFERENCE_API_KEY | Azure AI Inference provider | (blank) | Optional (fallback) | Key-based fallback; prefer leaving blank and using managed identity. |
| AZURE_CONTENT_SAFETY_ENDPOINT | Azure Content Safety | https://<example-content-safety>.cognitiveservices.azure.com | Required for Content Safety | Use the tenant Content Safety endpoint. Prefer Managed Identity. |
| AZURE_CONTENT_SAFETY_USE_MANAGED_IDENTITY | Azure Content Safety | unset | No | When true, force DefaultAzureCredential. If unset, provider uses API key when configured, else managed identity. |
| AZURE_CONTENT_SAFETY_KEY | Azure Content Safety | (blank) | Optional (fallback) | Key-based fallback (avoid committing). |
| AZURE_CONTENT_SAFETY_FLAG_SEVERITY | Content Safety / TAP | 0.7 | Optional | Threshold used for automated flagging in tools/workflows. |
| AZURE_SQL_SERVER | Storage / DB | server.database.windows.net | Required (if using Azure SQL) | When using managed identity, set AZURE_SQL_USE_MANAGED_IDENTITY=true. |
| AZURE_SQL_DATABASE | Storage / DB | mastra | Required (if using Azure SQL) | Name of the database. |
| AZURE_SQL_USE_MANAGED_IDENTITY | Storage / DB | true (recommended) | No | Preferred authentication method for Azure SQL. |
| AZURE_SQL_MANAGED_IDENTITY_CLIENT_ID | Storage / DB | (client-id) | Optional | Use when a user-assigned managed identity is required. |
| AUTH_API_BASE_URL | Auth / Integration tests | https://auth.example.com | Yes (for auth integrations) | Base URL used by auth helpers and tests. Required for integration runs. |
| AUTH_EMAIL / AUTH_PASSWORD / AUTH_API_KEY | Auth / tests | (dev credentials) | Required for local test auth | Provide either email/password or API key depending on test/run configuration. Avoid committing secrets. |
| APIM_GATEWAY_URL | APIM / runtime | https://<prefix>-apim.azure-api.net | Optional | Enables APIM-aware runtime behavior. When present, /admin/* routes expect the APIM-injected admin proxy header and internal probes can validate gateway connectivity. |
| ADMIN_PROXY_SHARED_SECRET | Admin routes / runtime | (Key Vault secret) | Optional | Shared secret used only when APIM is enabled. APIM injects it on runtime/operator /ai/admin/*; Admin UI/Replit browser callers should use /dashboard/admin-api/* in testing or local /admin-api/*. The app rejects direct /admin/* requests when the header is missing or wrong. Store it in Key Vault, not in source-controlled env files. |
| MASTRA_DB_URL | Mastra runtime | mssql://... | Optional (alternate) | If set, used by services to connect to the DB directly. |
| DB_CORE_SCHEMA / DB_WORKLOAD_SCHEMA / DB_HEALTH_SCHEMA | DB schemas | Core / K12SAFETY | Optional | Use to override default schemas used by DB queries and tools. |
| REASONING_DB_STEP_DATA / DB_STEP_DATA_ENABLED | Reasoning Engine / workflows | false | Optional | Toggle that controls whether the Reasoning Engine persists per-step DB state. Some tests and workflows rely on this. |
| K12_TEST_SERVER_URL / K12_TEST_SUBSCRIPTION_KEY / K12_TEST_BEARER_TOKEN | K12 tests | https://dev.example.com | Optional | Test harness variables used by the K12 integration suite. See tests/e2e/k12/ and packages/domain-k12/tests/ for current coverage. |
| K12_ANNEX_FORM_TYPE_IDS | K12 | comma-separated IDs | Optional | Form type filter used by Annex-helper logic. |
| TAP_API_BASE_URL / TAP_QUEUE_NAME / TAP_STORAGE_ACCOUNT | TAP integration | https://tap.example.com | Legacy | Removed TAP tool/workflow variables. The suggestions-only tagging route receives post data in the request body. |
| AZURE_INFERENCE_DEBUG_TIMINGS / AZURE_CONTENT_SAFETY_DEBUG_TIMINGS / MASTRA_DEBUG_TIMINGS | Debug | false | Optional | Enable additional timing and diagnostic logging. Do not enable in production unless troubleshooting. |
| MASTRA_SKIP_DOCS_MCP | MCP servers | false | Optional | Set to true to disable the Documentation MCP server at startup. |
| MASTRA_SKIP_K12_MCP | MCP servers | false | Optional | Set to true to disable the K12 Safety MCP server at startup. |
| MASTRA_SKIP_ADMIN_MCP | MCP servers | false | Optional | Set to true to disable the Admin MCP server at startup. |
| MASTRA_INCLUDE_REASONING_ENGINE | MCP servers / Reasoning | false | Optional | Must be set to true to enable the Reasoning Engine agents and MCP server. Default is off. |
| MASTRA_STARTUP_CHECKS | Startup | true | Optional | Enable/disable startup connectivity checks. |
| MASTRA_STARTUP_CHECKS_STRICT | Startup | true | Optional | When true, startup failures abort the process. |
| AZURE_STORAGE_ACCOUNT_NAME | Azure Storage | <storage-account> | Required for SDAC | Azure Storage Account name for SDAC cost report uploads. |
| AZURE_STORAGE_USE_MANAGED_IDENTITY | Azure Storage | true | Optional | Use Managed Identity for blob storage auth. |
| AZURE_STORAGE_CONNECTION_STRING | Azure Storage | (connection-string) | Optional (fallback) | Fallback connection string when Managed Identity is not used. |
| SDAC_UPLOAD_CONTAINER_NAME | SDAC | sdac-uploads | Optional | Blob container for SDAC cost report uploads. |
| SDAC_ARCHIVE_CONTAINER_NAME | SDAC | sdac-archive | Optional | Blob container for SDAC archived reports. |
| MOEOP_INTERNAL_BASE_URL | K12 / MOEOP | https://api-dev-internal.moeop.org | Required for K12 EOP | Base URL for the MOEOP internal API used by K12 EOP tools. |
| MOEOP_INTERNAL_AUTH_MODE | K12 / MOEOP | basic | Optional | Auth mode: basic (default) or jwt. |
| MOEOP_INTERNAL_USERNAME | K12 / MOEOP | (username) | Required when auth=basic | HTTP Basic auth username for MOEOP API. |
| MOEOP_INTERNAL_PASSWORD | K12 / MOEOP | (password) | Required when auth=basic | HTTP Basic auth password for MOEOP API. |
| TAVILY_API_KEY | Search | (api-key) | Required for web search | API key for Tavily web search integration. |
| PERPLEXITY_API_KEY | Search | (api-key) | Required for Perplexity | API key for Perplexity AI search integration. |
| LLM_PARAMS_CACHE_TTL_MS | LLM | 60000 | Optional | TTL in milliseconds for the DB-backed LLM parameter cache. |
| LLM_PARAMS_DB_OVERRIDES_DISABLED | LLM | false | Optional | Set to true to disable DB-backed LLM parameter overrides. |
| APPLICATIONINSIGHTS_CONNECTION_STRING | Telemetry | (connection-string) | Optional | Azure Application Insights connection string for distributed tracing. |
| K12_ENABLE_WORKFLOW_CANCELLATION | K12 | true | Optional | Enable/disable K12 workflow cancellation support. |
Notes & Best practices
- For Azure services, prefer using DefaultAzureCredential / Managed Identity. Documented provider behavior in the repo prefers Managed Identity-first — only use keys as a fallback for local debugging.
- Keep secret values in a secure store (Key Vault / GitHub Actions secrets) and reference them in CI, do not commit secrets into
.envfiles. - Where tests require credentials, use dedicated test accounts that have limited permissions and rotate keys frequently.
If desired, next steps are:
- Extract remaining per-project variables into a CSV and place it in
docusaurus-docs/static/assets/for download (done:assets/env-vars.csv) - Add a short guide describing how to configure Managed Identity for local development (done:
architecture/managed-identity-local)