# 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.

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](https://mastra.ai/docs/server/server-adapters/llms.txt) 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.

Read the [`mastra build`](https://mastra.ai/reference/cli/mastra/llms.txt) reference for all available flags.

## Build output

After building, Mastra creates the following structure:

```text
.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

Read the [`mastra start`](https://mastra.ai/reference/cli/mastra/llms.txt) 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](https://mastra.ai/docs/server/mastra-server/llms.txt). For all available options, see the [configuration reference](https://mastra.ai/reference/configuration/llms.txt).

## 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](https://mastra.ai/docs/server/custom-api-routes/llms.txt).

## 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](https://mastra.ai/docs/server/mastra-server/llms.txt) - Configure server behavior, middleware, and authentication
- [Server Adapters](https://mastra.ai/docs/server/server-adapters/llms.txt) - Use Express or Hono instead of `mastra build`
- [Custom API Routes](https://mastra.ai/docs/server/custom-api-routes/llms.txt) - Add custom HTTP endpoints
- [Configuration Reference](https://mastra.ai/reference/configuration/llms.txt) - Full configuration options