Workers
For usage patterns and deployment topologies, see Workers.
Environment variablesDirect link to Environment variables
MASTRA_WORKERSDirect link to mastra_workers
Controls which workers start in the current process.
| Value | Behavior |
|---|---|
| (not set) | Default workers are auto-created based on configuration |
"false" | Disables all event processing. The process only serves HTTP requests. |
"orchestration" | Only the orchestration worker starts |
"scheduler" | Only the scheduler worker starts |
"backgroundTasks" | Only the background task worker starts |
"orchestration,scheduler" | Multiple workers (comma-separated) |
Use this to run different worker types in separate containers from the same build artifact.
MASTRA_STEP_EXECUTION_URLDirect link to mastra_step_execution_url
The base URL of the API server, used by the orchestration worker to execute workflow steps remotely. Required when the orchestration worker runs in a separate process from the API.
MASTRA_STEP_EXECUTION_URL=http://api:4111/api
The orchestration worker sends step execution requests to:
${MASTRA_STEP_EXECUTION_URL}/workflows/:workflowId/runs/:runId/steps/execute
MASTRA_WORKER_AUTH_TOKENDirect link to mastra_worker_auth_token
A bearer token sent by the orchestration worker when calling the API's step execution endpoint. The API's configured auth provider must recognize this token. See Worker authentication.
MASTRA_WORKER_AUTH_TOKEN=sk-worker-secret-token
Worker typesDirect link to Worker types
OrchestrationWorkerDirect link to OrchestrationWorker
Processes workflow events from the PubSub workflows topic. Requires a pull-capable PubSub like @mastra/redis-streams or @mastra/google-cloud-pubsub configured with a pull subscription.
- Name:
orchestration - PubSub topic:
workflows - Consumer group:
mastra-orchestration
SchedulerWorkerDirect link to SchedulerWorker
Polls storage for due cron schedules and publishes workflow.start events.
- Name:
scheduler - Single instance only: Run exactly one instance to avoid duplicate fires
BackgroundTaskWorkerDirect link to BackgroundTaskWorker
Executes background tool calls dispatched by agents.
- Name:
backgroundTasks - PubSub topic:
background-tasks - Consumer group:
background-task-workers - Supports multiple replicas: Instances share the consumer group
Supported storage backendsDirect link to Supported storage backends
A deployment running all worker types requires a storage backend that implements the workflows, backgroundTasks, and schedules domains. The schedules domain is specifically required by the SchedulerWorker. If you don't use scheduled workflows, backends without it can still support orchestration and background tasks. The following backends support all three:
| Backend | Package |
|---|---|
| PostgreSQL | @mastra/pg |
| LibSQL | @mastra/libsql |
| MySQL | @mastra/mysql |
| MongoDB | @mastra/mongodb |
| Spanner | @mastra/spanner |
| Convex | @mastra/convex |
Other storage backends (Upstash, DynamoDB, Cloudflare D1, ClickHouse, Redis) support workflows and some worker features, but are missing the schedules domain. They can still be used for orchestration and background task workers if you don't deploy the scheduler.