> Discover all available pages from the documentation index: https://mastra.zisheng.pro/en/llms.txt

# 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](https://mastra.zisheng.pro/en/docs/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. Read the [`mastra build`](https://mastra.zisheng.pro/en/reference/cli/mastra) 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.zisheng.pro/en/reference/cli/mastra) reference for all available flags.

## Build configuration

### Build-time configuration

Mastra reads the `bundler`, `deployer`, and `server` options while it builds your application. Keep those options as direct properties of the object passed to `new Mastra()` so the build can extract them.

The following entry-file shape works:

```typescript
import { Mastra } from '@mastra/core/mastra'

export const mastra = new Mastra({
  bundler: {
    externals: ['sharp'],
  },
  server: {
    port: 4111,
  },
})
```

The value of each option can come from a variable, import, or function call. The option itself must remain a direct property. Don't hide build-time options behind a factory call or an object spread:

```typescript
const options = {
  bundler: {
    externals: ['sharp'],
  },
}

// These patterns prevent Mastra from extracting `bundler` during the build.
export const mastra = new Mastra(createMastraOptions())
export const otherMastra = new Mastra({ ...options })
```

When Mastra can't extract an option, it uses the default build behavior for that option. See the [configuration reference](https://mastra.zisheng.pro/en/reference/configuration) for the available `bundler`, `deployer`, and `server` settings.

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