Skip to main content

Workers

beta

This feature is in beta. The API is stable enough for production use, but some details may change. See known limitations for current gaps.

Workers handle background processing outside the request-response cycle. Workflow step execution, cron-based scheduling, and long-running tool calls all run in workers, keeping the API responsive.

By default, workers run in the same process as the API. For production workloads, you can split them into separate processes or containers and scale each one independently.

When to use workers
Direct link to When to use workers

Workers matter when any of these apply:

  • Workflow steps take more than a few seconds and shouldn't block API responses
  • You need event durability so in-flight work survives process restarts
  • Different parts of the system need to scale independently (e.g., more orchestration capacity without more API instances)
  • Background tool calls should run on dedicated compute

If your application handles light traffic and workflows complete quickly, the default in-process setup works fine. Skip the worker infrastructure until you need it.

Worker types
Direct link to Worker types

Mastra has three built-in worker types. Each handles a specific kind of background processing.

Orchestration worker
Direct link to Orchestration worker

Subscribes to workflow events on the PubSub bus and executes workflow steps. Every workflow.start, step transition, and lifecycle event flows through this worker.

In a split deployment, the orchestration worker pulls events from a distributed PubSub backend and delegates step execution back to the API over HTTP. In-process, it runs steps directly.

The orchestration worker requires a PubSub backend that supports pull mode (e.g., RedisStreamsPubSub or GoogleCloudPubSub).

Scheduler worker
Direct link to Scheduler worker

Polls storage for due cron schedules and publishes workflow.start events. It is a producer only, meaning it creates work for the orchestration worker to pick up.

The scheduler reads declarative schedule fields from your workflow definitions automatically. See Scheduled workflows for how to declare schedules.

Do not run more than one scheduler instance. Multiple schedulers polling the same storage would fire duplicate events for the same schedule.

Background task worker
Direct link to Background task worker

Executes agent tool calls marked with background: { enabled: true }. When an agent invokes a background tool, the API dispatches the task to this worker instead of blocking the response stream.

The background task worker manages concurrency limits, task lifecycle, and result delivery through the PubSub bus.

How workers run
Direct link to How workers run

In-process (default)
Direct link to In-process (default)

With no configuration, Mastra creates and starts workers inside the API process. Events flow through an in-memory PubSub, and everything shares a single Node.js runtime.

src/mastra/index.ts
import { Mastra } from '@mastra/core/mastra'

export const mastra = new Mastra({
  // Workers run in-process by default.
  // No pubsub or worker config needed.
})

This setup needs no external infrastructure beyond your storage adapter. It doesn't survive process crashes, and you can't scale individual components.

Split processes
Direct link to Split processes

To run workers separately, configure a distributed PubSub backend and use the MASTRA_WORKERS environment variable to control which workers start in each process.

src/mastra/index.ts
import { Mastra } from '@mastra/core/mastra'
import { RedisStreamsPubSub } from '@mastra/redis-streams'
import { PostgresStore } from '@mastra/pg'

export const mastra = new Mastra({
  storage: new PostgresStore({
    connectionString: process.env.DATABASE_URL!,
  }),
  pubsub: new RedisStreamsPubSub({
    url: process.env.REDIS_URL!,
  }),
})

Any supported storage backend works — swap the storage adapter for your preferred database.

Run the same build artifact in multiple containers, each with a different MASTRA_WORKERS value to control which worker starts in each process.

Split deployments require a distributed PubSub backend (RedisStreamsPubSub or GoogleCloudPubSub), a shared storage backend, and network connectivity between the orchestration worker and the API.

The worker deployment guide walks through this setup with a Docker Compose example.

Network architecture
Direct link to Network architecture

Workers are internal infrastructure. They are not exposed to end users and do not need their own subdomain, public URL, or inbound HTTP route.

In a split deployment:

  • The API server is the only public-facing process. It serves all client HTTP requests — REST endpoints, agent interactions, workflow triggers, and any custom routes.
  • Workers connect outbound only. They pull events from the distributed PubSub backend and read/write to the shared storage database. They do not accept inbound traffic from clients.
  • The orchestration worker calls the API internally. It sends step execution requests to the API over the container network using MASTRA_STEP_EXECUTION_URL. This is internal service-to-service communication, not a public endpoint.

All three worker types (orchestration, scheduler, background task) sit behind the API on a private network. They share access to the PubSub backend and storage database but never receive traffic directly from clients. If a worker-related feature needs an HTTP route (for example, token minting for a voice integration), that route runs on the API server, not on the worker process.

Known limitations
Direct link to Known limitations

  • No dead-letter queue: Failed events are nacked and retried, but there is no DLQ for events that repeatedly fail.
  • No built-in health endpoint: Workers don't expose an HTTP health check. Use container-level liveness probes or process monitoring.
  • Scheduler is single-instance: Running multiple scheduler processes causes duplicate schedule fires.
  • Runs stuck in "running" after API crash: If the API process crashes while executing a workflow step, the run remains in running status with no automatic retry. For durable agents, set recovery.durableAgents to 'auto' in the Mastra config to automatically re-drive orphaned runs on server restart. See Crash recovery for details.
On this page