Deploy Mastra to Kubernetes

Run a Mastra application across multiple pods on Kubernetes, so it scales horizontally behind a load balancer. Because each pod is a separate process, the pods must share a pub/sub backend and a database, otherwise work started on one pod is invisible to the others.

info

This guide covers deploying the Mastra server. If you're using a server adapter or web framework, deploy the way you normally would for that framework.

warning

Multi-pod support relies on durable agents, which are currently in beta. APIs may change in minor versions. Read Known limitations before you rely on this in production.

Before you begin

You'll need:

• A Mastra application
• A Kubernetes cluster and kubectl
• A container registry your cluster can pull from
• A shared Redis instance, reachable from every pod
• A shared PostgreSQL database, reachable from every pod

Why multiple pods need shared infrastructure

A single pod keeps run state in its own memory. With one pod that's fine, because every request reaches the same process. Across pods it breaks: a browser might stream from pod A while the user's next request is routed to pod B, and pod B has no record of the run on pod A.

Redis and Postgres close that gap:

• Pub/sub carries events between pods. When an event is published on one pod, the others receive it. Mastra uses RedisStreamsPubSub, which also provides the per-thread leasing that keeps a single pod as the owner of a conversation at a time. See PubSub.
• Storage persists run state. Durable agents save each run as a workflow snapshot, so any pod can resume a run from the database after a restart or when a request is routed elsewhere.

Configure shared infrastructure

Point the Mastra instance at Redis and Postgres. Read the connection details from environment variables so the same image runs in every pod.

Install the backends:

npm

npm install @mastra/redis-streams @mastra/pg @mastra/redis ioredis

pnpm

pnpm add @mastra/redis-streams @mastra/pg @mastra/redis ioredis

Yarn

yarn add @mastra/redis-streams @mastra/pg @mastra/redis ioredis

Bun

bun add @mastra/redis-streams @mastra/pg @mastra/redis ioredis

Configure pub/sub, storage, and a shared cache on the Mastra instance:

src/mastra/index.ts

import { Mastra } from '@mastra/core'
import { RedisStreamsPubSub } from '@mastra/redis-streams'
import { RedisServerCache } from '@mastra/redis'
import { PostgresStore } from '@mastra/pg'
import Redis from 'ioredis'

export const mastra = new Mastra({
  // Carries events between pods, and provides
  // per-thread leases so one pod owns a conversation at a time.
  pubsub: new RedisStreamsPubSub({
    url: process.env.REDIS_URL!,
  }),
  // Persists run state so any pod can resume a run.
  storage: new PostgresStore({
    id: 'mastra-storage',
    connectionString: process.env.DATABASE_URL!,
  }),
  // Shared event cache so a reconnecting client can replay missed chunks
  // from any pod, not only the one that started the run.
  cache: new RedisServerCache({ client: new Redis(process.env.REDIS_URL!) }),
})

The cache is what makes resumable streams work across pods. A reconnecting client replays missed events from this cache, so it must be shared. The default in-memory cache only serves replays within one process.

Use durable agents

A plain Agent keeps its stream and approval state in one pod's memory, so those don't survive a request landing on another pod. A durable agent runs the agentic loop inside a workflow and persists its state, so any pod can observe or resume the same run.

Wrap the agent with createDurableAgent():

src/mastra/agents/assistant.ts

import { Agent } from '@mastra/core/agent'
import { createDurableAgent } from '@mastra/core/agent/durable'

const agent = new Agent({
  id: 'assistant',
  name: 'Assistant',
  instructions: 'You are a helpful assistant.',
  model: 'openai/gpt-5.5',
})

export const durableAssistant = createDurableAgent({ agent })

Register the durable agent with the Mastra instance above. Its run state now lives in Postgres and its events flow through Redis, so the run is reachable from every pod.

Deploy

1. Build and containerize the Mastra server, then push the image to your registry. Follow the Mastra server guide for the build, and ensure the server reads process.env.PORT and listens on 0.0.0.0.

2. Store the shared connection strings as a Secret:

   kubectl create secret generic mastra-secrets \
     --from-literal=REDIS_URL='redis://redis:6379' \
     --from-literal=DATABASE_URL='postgresql://user:pass@postgres:5432/mastra'

3. Apply a Deployment that runs the image, reading the shared Secret. Start with one replica so the first pod creates the database schema on its own, then scale up in the next step:

   deployment.yaml

   apiVersion: apps/v1
   kind: Deployment
   metadata:
     name: mastra
   spec:
     replicas: 1
     selector:
       matchLabels:
         app: mastra
     template:
       metadata:
         labels:
           app: mastra
       spec:
         containers:
           - name: mastra
             image: your-registry/mastra:latest
             ports:
               - containerPort: 8080
             env:
               - name: PORT
                 value: '8080'
             envFrom:
               - secretRef:
                   name: mastra-secrets
             readinessProbe:
               tcpSocket:
                 port: 8080
             livenessProbe:
               tcpSocket:
                 port: 8080
             resources:
               requests:
                 cpu: 500m
                 memory: 512Mi

   The resources.requests.cpu value is required for the HorizontalPodAutoscaler below. Kubernetes calculates CPU utilization as usage divided by the requested amount, so without a CPU request the autoscaler can't compute a target and won't scale.

   kubectl apply -f deployment.yaml

   Once the first pod is ready, scale up:

   kubectl wait --for=condition=available deployment/mastra
   kubectl scale deployment/mastra --replicas=3

   note

   Every replica runs the same image and connects to the same Redis and Postgres. That shared infrastructure, not the pod count, is what lets runs cross pods.

4. Expose the Deployment with a Service:

   service.yaml

   apiVersion: v1
   kind: Service
   metadata:
     name: mastra
   spec:
     selector:
       app: mastra
     ports:
       - port: 80
         targetPort: 8080

   kubectl apply -f service.yaml

5. Scale the replicas automatically with a HorizontalPodAutoscaler:

   hpa.yaml

   apiVersion: autoscaling/v2
   kind: HorizontalPodAutoscaler
   metadata:
     name: mastra
   spec:
     scaleTargetRef:
       apiVersion: apps/v1
       kind: Deployment
       name: mastra
     minReplicas: 3
     maxReplicas: 10
     metrics:
       - type: Resource
         resource:
           name: cpu
           target:
             type: Utilization
             averageUtilization: 70

   kubectl apply -f hpa.yaml

   note

   CPU-based autoscaling needs the metrics-server running in the cluster. Managed clusters like GKE, EKS, and AKS include it. Local clusters like kind and minikube don't, so enable it there first (for example, minikube addons enable metrics-server).

6. Verify the pods are running:

   kubectl get pods -l app=mastra

   Forward the service in one terminal. This command stays in the foreground:

   kubectl port-forward service/mastra 8080:80

   In a second terminal, call the API:

   curl http://localhost:8080/api/agents

   A JSON list of your agents means the deployment is serving.

   warning

   Set up authentication before exposing your endpoints publicly.

Streaming and reconnection

A durable agent publishes stream chunks to a per-run topic through the shared pub/sub. A client that disconnects reconnects by calling observe() with the run's ID, and replays the chunks it missed from the shared cache:

src/server/reconnect.ts

const { output, cleanup } = await durableAssistant.observe(runId)

for await (const chunk of output.fullStream) {
  // Chunks from the run, including any missed while disconnected
}

cleanup()

Because the run state is in Postgres and the events are in Redis, the reconnecting request can be served by any pod, not only the one that started the run. See Resumable streams.

Multiple clients can observe the same run at once. Each observe() call receives the full stream, so a user watching from two devices, or two people following the same run, stay in sync.

Tool approval across pods

A durable agent pauses on a tool call until a human approves it. Because the suspended run is saved to Postgres, the approval can arrive on any pod, not only the one that started the run.

Start a run that requires approval:

src/server/approval.ts

const { runId } = await durableAssistant.stream('Delete the archived records', {
  requireToolApproval: true,
  memory: { thread: 'thread-1', resource: 'user-1' },
})

The run suspends before the tool runs. Approve it later, from any pod:

await durableAssistant.resume(runId, { approved: true })

The pod that handles the approval loads the suspended run from Postgres. It then runs the approved tool and publishes the result over the shared pub/sub, so a client observing the run receives the continuation. See Tool approval.

Known limitations

• The default in-process setup keeps run state in one pod's memory and doesn't share it across pods. Use durable agents with shared Redis and Postgres so streaming, approvals, and reconnection work across pods.
• Cross-pod streaming, approvals, and reconnection require the durable-agent path. A plain agent keeps run state in memory and doesn't resume on another pod.
• When multiple pods start at once against an uninitialized database, they can race to create the schema and a pod may fail to start. Start with one replica so the schema is created once, then scale up.
• For a stricter setup, initialize the schema outside the app (for example, a one-off Kubernetes Job) and set disableInit: true on the PostgresStore in every pod.

Related

• PubSub
• Durable agents
• Mastra server
• Deployment overview