Skip to Content
DocsDeploymentWith a Server

Creating A Mastra Server

While developing or when you deploy a Mastra application, it runs as an HTTP server that exposes your agents, workflows, and other functionality as API endpoints. This page explains how to configure and customize the server behavior.

Server Architecture

Mastra uses Hono  as its underlying HTTP server framework. When you build a Mastra application using mastra build, it generates a Hono-based HTTP server in the .mastra directory.

The server provides:

  • API endpoints for all registered agents
  • API endpoints for all registered workflows
  • Custom api route supports
  • Custom middleware support
  • Configuration of timeout
  • Configuration of port
  • Configuration of body limit

See the Middleware and Custom API Routes pages for details on adding additional server behaviour.

Server configuration

You can configure server port and timeout in the Mastra instance.

import { Mastra } from "@mastra/core";
 
export const mastra = new Mastra({
  server: {
    port: 3000, // Defaults to 4111
    timeout: 10000, // Defaults to 30000 (30s)
  },
});

The method option can be one of "GET", "POST", "PUT", "DELETE" or "ALL". Using "ALL" will cause the handler to be invoked for any HTTP method that matches the path.

Custom CORS Config

Mastra allows you to configure CORS (Cross-Origin Resource Sharing) settings for your server.

import { Mastra } from "@mastra/core";
 
export const mastra = new Mastra({
  server: {
    cors: {
      origin: ["https://example.com"], // Allow specific origins or '*' for all
      allowMethods: ["GET", "POST", "PUT", "DELETE", "OPTIONS"],
      allowHeaders: ["Content-Type", "Authorization"],
      credentials: false,
    },
  },
});

Deployment

Since Mastra builds to a standard Node.js server, you can deploy to any platform that runs Node.js applications:

  • Cloud VMs (AWS EC2, DigitalOcean Droplets, GCP Compute Engine)
  • Container platforms (Docker, Kubernetes)
  • Platform as a Service (Heroku, Railway)
  • Self-hosted servers

Building

Build the application:

# Build from current directory
mastra build
 
# Or specify a directory
mastra build --dir ./my-project

The build process:

  1. Locates entry file (src/mastra/index.ts or src/mastra/index.js)
  2. Creates .mastra output directory
  3. Bundles code using Rollup with tree shaking and source maps
  4. Generates Hono  HTTP server

See mastra build for all options.

Running the Server

Start the HTTP server:

node .mastra/output/index.mjs

Enable Telemetry for build output

Load instrumentation for the build output like so:

node --import=./.mastra/output/instrumentation.mjs  .mastra/output/index.mjs

Serverless Deployment

Mastra also supports serverless deployment on Cloudflare Workers, Vercel, and Netlify.

See our Serverless Deployment guide for setup instructions.

OverviewMiddleware