Deployment & Operations

Deployment & Operations

This page covers deployment modes, environment variables, and operational best practices for running the Mastra Agent Framework in development and production environments.

Supported Deployment Targets

1. Local Development

• Run via npm run dev for active development with hot-reload
• Uses local LibSQL database (.mastra/data/mastra.db) for Mastra runtime state
• Connects to Azure SQL for operational logging and agent profiles
• Telemetry disabled by default (MASTRA_TELEMETRY_DISABLED=true)

2. Azure App Service (Production)

• Deployed via GitHub Actions
• Container-based deployment using Docker
• Managed Identity authentication for Azure services (OpenAI, Content Safety, SQL)
• staging and prod use slot-based releases with staging + rollback slots
• Auto-scaling based on load

Deployment Modes

Mode	Command	Use Case	Database	Telemetry
Development	npm run dev	Local development, debugging	Local LibSQL + Azure SQL	Disabled
Production Build	npm run build	Create production artifacts	Azure SQL	Enabled
Production Run	npm run start (runs mastra start)	Run built artifacts	Azure SQL	Enabled

Container Architecture

The production deployment runs the main application container on each App Service. The container is built from the repo root Dockerfile, pushed to Azure Container Registry, and deployed by GitHub Actions.

Deployment Workflow Flow

A full environment deployment follows this order:

For environment changes, GitHub workflows orchestrate infrastructure, deployment, reconciliation, validation, and smoke checks.

Production Slot Strategy

dev and test deploy directly to production because they use lower-cost plans without deployment slots. staging and prod now use a two-slot release model:

• staging: receives the newly deployed image first
• rollback: keeps the last production image so rollback is a slot swap, not a rebuild

The deploy flow is:

1. Sync the full runtime settings set to production and every discovered slot.
2. Deploy the new build to the staging slot.
3. Run smoke checks against the slot hostname.
4. Wait for a GitHub environment approval.
5. Snapshot current production into rollback.
6. Swap staging to production.
7. Automatically swap rollback back if post-swap health fails.

The swap stage fans out in parallel for the slot-managed HTTP services to minimize partial-cutover time.

Required Environment Variables

Core (All Environments):

• AZURE_SQL_SERVER - SQL Server hostname for operational data
• AZURE_SQL_DATABASE - Database name
• AZURE_INFERENCE_ENDPOINT - Azure AI Inference endpoint for LLM provider

Authentication (Production):

• AZURE_SQL_USE_MANAGED_IDENTITY=true - Use Managed Identity for SQL auth
• AZURE_FOUNDRY_USE_MANAGED_IDENTITY=true - Use Managed Identity for AI Inference auth
• AZURE_CONTENT_SAFETY_USE_MANAGED_IDENTITY=true - Force Managed Identity for Content Safety (otherwise API key is used when configured)

Workload Selection:

• MASTRA_TARGET - Target workload to run (all, k12, tap, reasoning-engine)

Optional Integrations:

• REASONING_DB_STEP_DATA - Enable database-backed step data storage
• K12_TEST_SERVER_URL - K12 integration test endpoint
• TAP_API_BASE_URL - TAP API integration endpoint

For the complete environment variable matrix, see Environment Variables.

Operational Endpoints

Every deployed instance exposes these endpoints:

Endpoint	Auth	Description
/health	None	Application health check (returns 200 if running)
/api/agents	Easy Auth	List registered agents
/api/tools	Easy Auth	List registered tools
/admin/*	APIM-injected admin proxy secret when APIM is enabled	Admin dashboard and management APIs. Direct app-host requests are rejected unless APIM injects the shared admin proxy header.

When APIM is enabled, all deployed HTTP backends are also published through the gateway:

APIM Path Prefix	Backend
/ai	Main Mastra app
/func	Main Function App
/ingestion	Ingestion Server
/ingestion-func	Ingestion Function App
/widget	Widget app
/dashboard	Dashboard app

These APIM routes require the normal APIM auth combination unless the API policy explicitly exempts a path:

• Authorization: Bearer <token>
• Ocp-Apim-Subscription-Key: <key>

Current exemptions:

• /ai/admin/* is a runtime/operator APIM path, not the Admin UI/Replit browser path. UI callers should use /dashboard/admin-api/* in testing or local /admin-api/*. APIM injects the internal X-Mastra-Admin-Proxy-Secret header before forwarding to the app.
• /api/mcp/* keeps the existing APIM JWT bypass
• /dashboard/* remains subscription-key-only

Deployment Checklist

When deploying to a new environment:

1. Infrastructure: Run the GitHub infrastructure workflow or deploy Bicep templates manually
2. GitHub OIDC identity: Configure Azure permissions for the GitHub environment identity
3. AI Models: Deploy model endpoints via the Deploy Model Runtime workflow (guide)
4. OAuth: Set up Entra app registrations for APIM authentication
5. APIM: Publish all HTTP backends and apply Easy Auth
6. Database: Run DACPAC publish to create/update schema, then seed data
7. Verify: Check APIM routes and slot health to confirm all services are healthy

What to Read Next

• Azure Deployment - CI/CD workflow architecture and container runtime
• AI Model Deployment - Deploy Model Runtime workflow reference
• Infrastructure Overview - Full Azure architecture diagram
• Environment Variables - Complete variable matrix