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 /openapi.json	OpenAPI specification (if server.build.openAPIDocs is enabled)
GET /swagger-ui	Interactive API documentation (if server.build.swaggerUI is enabled)

This list is not 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