---
title: "Deploy a Mastra Server | Deployment"
description: "Learn how to build and deploy a Mastra server."
packages:
  - "@mastra/deployer"
---

# 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](/docs/v1/server/server-adapters) instead.

:::

## Building your application

Run the build command from your project root:

```bash
mastra build
```

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

:::info

Read the [`mastra build`](/reference/v1/cli/mastra#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:

```bash
mastra start
```

Or run directly with Node.js:

```bash
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/v1/cli/mastra#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](/docs/v1/server/mastra-server). For all available options, see the [configuration reference](/reference/v1/configuration).

## 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](/docs/v1/server/custom-api-routes).

## Troubleshooting

### Memory errors during build

If you encounter `JavaScript heap out of memory` errors:

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

## Related

- [Server Overview](/docs/v1/server/mastra-server) - Configure server behavior, middleware, and authentication
- [Server Adapters](/docs/v1/server/server-adapters) - Use Express or Hono instead of `mastra build`
- [Custom API Routes](/docs/v1/server/custom-api-routes) - Add custom HTTP endpoints
- [Configuration Reference](/reference/v1/configuration) - Full configuration options
