Deploy a Mastra server

Trust: ★★★☆☆ (0.90) · 0 validations · developer_reference

Published: 2026-05-10 · Source: crawler_authoritative

Tình huống

Guide for deploying Mastra applications as a standalone Node.js server using mastra build and mastra start commands, targeting developers building production applications.

Insight

Mastra compiles applications into a standalone Node.js/Bun/Deno server. Run mastra build from the project root to create a .mastra directory containing a production-ready server. The build output structure includes: .mastra/.build/ for intermediate artifacts, and .mastra/output/ containing index.mjs (server entry point), mastra.mjs (bundled config), tools.mjs (aggregated tool exports), tools/ (individual tool bundles), package.json, node_modules/, .npmrc, public/ (static assets from src/mastra/public), and playground/ (Studio UI with --studio flag). The output directory is self-contained and can be copied to any server. The build process uses Rollup with tree-shaking and optional source maps to create a Hono-based HTTP server. Run the server with mastra start (loads .env.production and .env, provides helpful error messages, handles graceful shutdown) or directly with node .mastra/output/index.mjs. The server exposes /health (200 OK health check), /api/openapi.json (OpenAPI spec if enabled), and /swagger-ui (interactive docs if enabled). Run mastra dev and visit http://localhost:4111/swagger-ui to view all endpoints. For memory errors during build, use NODE_OPTIONS="--max-old-space-size=4096" mastra build.

Hành động

To deploy a Mastra application: 1) Run mastra build from project root to create the production build. 2) Copy the .mastra/output directory to your target server. 3) Start the server with mastra start or node .mastra/output/index.mjs. 4) Set environment variables as needed: PORT (default 4111), MASTRA_STUDIO_PATH, MASTRA_SKIP_DOTENV, NODE_OPTIONS. 5) Access health endpoint at /health and API docs at /swagger-ui if enabled in config. For Express/Hono integration instead of standalone server, use Server Adapters.

Kết quả

Returns a running standalone Hono-based HTTP server that serves agents, workflows, and health check endpoints. Health checks return 200 OK. OpenAPI and Swagger UI endpoints provide API documentation when enabled via server.build.openapiDocs and server.build.swaggerUI configuration.

Điều kiện áp dụng

Server runs on any platform supporting Node.js, Bun, or Deno. Build requires sufficient memory; use NODE_OPTIONS for large builds.

---

Nội dung gốc (Original)

Deploy a Mastra server

Mastra compiles your application into a standalone Node.js server that can run on any platform supporting Node.js, Bun, or Deno.

Tip: This guide covers deploying the standalone server generated by mastra build. If you need to integrate Mastra into an existing Express or Hono application, see Server Adapters instead.

Building your application

Run the build command from your project root:

mastra build

This creates a .mastra directory containing your production-ready server.

Info: Read the mastra build reference for all available flags.

Build output

After building, Mastra creates the following structure:

.mastra/
├── .build/                # Intermediate build artifacts (module maps, analysis)
└── output/
    ├── index.mjs          # Server entry point
    ├── mastra.mjs         # Your bundled Mastra configuration
    ├── tools.mjs          # Aggregated tool exports
    ├── tools/             # Individual tool bundles
    ├── package.json       # Production dependencies
    ├── node_modules/      # Installed dependencies
    ├── .npmrc             # Copied from your project (if present)
    ├── public/            # Static assets (if src/mastra/public exists)
    └── playground/        # Studio UI (if --studio flag used)

The output directory is self-contained. You can copy it to any server and run it directly.

Running the server

Start the server using the Mastra CLI:

mastra start

Or run directly with Node.js:

node .mastra/output/index.mjs

The mastra start command provides additional features:

• Loads environment variables from .env.production and .env
• Provides helpful error messages for missing modules
• Handles process signals for graceful shutdown

Info: Read the mastra start reference for all available flags.

Build configuration

Public folder

If a public folder exists in your Mastra directory (src/mastra/public), its contents are copied to the output directory during build. These files are served as static assets by the server.

Mastra configuration

The build process respects configuration in your Mastra instance. For server behavior like CORS, timeouts, and middleware, see server overview. For all available options, see the configuration reference.

Build process

The build follows these steps:

1. Locates entry file: Finds index.ts or index.js in your Mastra directory.
2. Discovers tools: Scans for tool files matching {mastraDir}/tools/**/*.{js,ts}, excluding test files.
3. Analyzes dependencies: Determines which packages to bundle vs. install externally.
4. Bundles code: Uses Rollup with tree-shaking and optional source maps.
5. Generates server: Creates a Hono-based HTTP server as index.mjs.
6. Installs dependencies: Runs npm install in the output directory.
7. Copies assets: Copies public folder and .npmrc if present.

Environment variables

Variable	Description
PORT	Server port (default: 4111)
MASTRA_STUDIO_PATH	Path to Studio build directory (default: ./playground)
MASTRA_SKIP_DOTENV	Skip loading .env files when set
NODE_OPTIONS	Node.js options (e.g., --max-old-space-size=4096 for build memory issues)

Server endpoints

The built server exposes endpoints for health checks, agents, workflows, and more:

Endpoint	Description
GET /health	Health check endpoint, returns 200 OK
GET /api/openapi.json	OpenAPI specification (if server.build.openAPIDocs is enabled).
GET /swagger-ui	Interactive API documentation (if server.build.swaggerUI is enabled)

This list isn’t exhaustive. To view all endpoints, run mastra dev and visit http://localhost:4111/swagger-ui.

To add your own endpoints, see Custom API Routes.

Troubleshooting

Memory errors during build

If you encounter JavaScript heap out of memory errors:

NODE_OPTIONS="--max-old-space-size=4096" mastra build

Related

• Server Overview: Configure server behavior, middleware, and authentication
• Server Adapters: Use Express or Hono instead of mastra build
• Custom API Routes: Add custom HTTP endpoints
• Configuration Reference: Full configuration options

Liên kết

• Nền tảng: Dev Framework · Mastra
• Nguồn: https://mastra.ai/docs/deployment/mastra-server

Xem thêm:

• Mastra Deployment Overview
• Mastra Platform Overview
• Deploy in a Monorepo
• Server Overview - Mastra HTTP Server Configuration
• Mastra Studio Overview - Interactive UI for Agent Development