Introducing the Mastra Helm Chart for Self-Hosted Deployments

Today we're announcing the Mastra Helm chart for self-hosting Mastra on Kubernetes clusters.

The Helm chart deploys the same topology we use in the Mastra platform to run customer projects at scale. Shaped by everything we've learned since the platform launched earlier this year, we're now shipping our playbook so you can run Mastra projects the way we do.

You've always been able to deploy Mastra on your own infrastructure. Our docs cover self-hosting Mastra server, and cloud provider deploys for popular services. Plus, Mastra also ships an extendable deployer class and pre-built deployers for Vercel, Cloudflare, and Netlify.

Why we built the Helm chart

Customers self-hosting Mastra regularly asked for our recommended way to deploy. We put the Helm chart together to give them a solid base to build on. The templates offer a faster path from 0 to 1, while remaining flexible with overrides.

The helm chart includes templates for:

• mastra-projects: The umbrella chart (Gateway, ClusterIssuer)
• mastra-server: Deployment, Service, Ingress, HPA, PDB, NetworkPolicy, Secret
• mastra-studio: Same as mastra-server but for the Studio UI
• mastra-common: Shared helpers for env management, cloud annotations, and security defaults

We're starting with support for GKE (Google Cloud), EKS (AWS), generic, and local (kind, k3s), with Azure (AKS) to follow.

How to deploy

Build your Mastra project using mastra build --studio and push it to a container registry your cluster can pull from. Create a Kubernetes Secret with your database URL, license key, and any provider API keys your agents need:

kubectl create namespace mastra
kubectl create secret generic mastra-app-env -n mastra \
  --from-literal=DATABASE_URL='postgresql://user:pass@host:5432/mastra' \
  --from-literal=MASTRA_EE_LICENSE='<your-license-key>' \
  --from-literal=ANTHROPIC_API_KEY='<provider-key>'

A valid mastra-values.yaml needs your image, secret name, and cloud platform. Set global.cloud to one of: gke (Google Kubernetes Engine), eks (Amazon Elastic Kubernetes Service), generic, or local (kind, k3s), and the chart emits the correct LoadBalancer and Ingress annotations for that platform:

global:
  cloud: gke
 
mastra-server:
  image:
    repository: your-registry/my-mastra-app
    tag: "1.0.0"
  existingSecret: mastra-app-env
 
mastra-studio:
  image:
    repository: your-registry/my-mastra-app
    tag: "1.0.0"
  existingSecret: mastra-app-env

Install the chart from the OCI registry:

helm install mastra \
  oci://us-central1-docker.pkg.dev/mastra-cloud/mastra-helm-ee/mastra-projects \
  --version 0.2.0 \
  -n mastra -f mastra-values.yaml

Tune for your workload

Different agents have different needs. Some handle short bursts of one-or-two-turn requests called at high volume; others run longer sessions but get called less often. The chart's defaults are a starting point — override any template value from your mastra-values.yaml to tune replicas, autoscaling, resource requests, and network exposure to suit your workload.

For example, extend the mastra-values.yaml file with an ingress exposure mode + cert-manager for TLS, server resource requests, and horizontal autoscaling:

global:
  # ...
  exposure:
    mode: ingress
  tls:
    clusterIssuer: letsencrypt
 
tls:
  letsEncrypt:
    email: ops@example.com
 
mastra-server:
  # ...
  ingress:
    host: api.example.com
  resources:
    requests:
      cpu: 250m
      memory: 512Mi
  autoscaling:
    enabled: true
    minReplicas: 2
    maxReplicas: 5
    targetCPUUtilizationPercentage: 80
 
mastra-studio:
  # ...
  ingress:
    host: studio.example.com

Enterprise Edition features

The Mastra Helm chart requires an Enterprise Edition (EE) license to access the private OCI registry. An EE license also unlocks the following Mastra runtime features:

• Agent Builder: The in-Studio editor for team members
• RBAC: Role-based access control
• FGA: Fine-grained authorization
• ACL: Access control lists
• SSO: Single sign-on

Try it out

Book a call and we'll get you set up.

For full setup instructions, see the Kubernetes (Helm) docs.