Configuration

The following reference covers all supported options in Mastra. You initialize and configure Mastra by instantiating the Mastra class.

src/mastra/index.ts

import { Mastra } from '@mastra/core'

export const mastra = new Mastra({
  // Your options...
})

Top-level options

agents

Type: Record<string, Agent>

A record of agent instances keyed by their names. Agents are autonomous systems that can make decisions and take actions using AI models, tools, and memory.

Visit the Agents documentation to learn more.

src/mastra/index.ts

import { Mastra } from '@mastra/core'
import { Agent } from '@mastra/core/agent'

export const mastra = new Mastra({
  agents: {
    weatherAgent: new Agent({
      id: 'weather-agent',
      name: 'Weather Agent',
      instructions: 'You help with weather information',
      model: 'openai/gpt-5.6-sol',
    }),
  },
})

backgroundTasks

Type: BackgroundTaskManagerConfig

Enables and configures the background task manager. When enabled, agents can dispatch long-running tool calls (including subagent invocations) to run asynchronously while the agentic loop continues. Tasks are persisted, so a configured storage backend is required.

Visit the Background tasks documentation to learn more.

src/mastra/index.ts

import { Mastra } from '@mastra/core'
import { LibSQLStore } from '@mastra/libsql'

export const mastra = new Mastra({
  storage: new LibSQLStore({
    id: 'mastra-storage',
    url: 'file:./mastra.db',
  }),
  backgroundTasks: {
    enabled: true,
    globalConcurrency: 10,
    perAgentConcurrency: 5,
    backpressure: 'queue',
    defaultTimeoutMs: 300_000,
  },
})

enabled:

boolean

= false

Whether the background task manager is available. The manager only initializes when this is true and a storage backend is configured. This is a feature-availability switch — it does not opt any tool into background dispatch. Tools must opt in at the tool or agent layer (see the Background tasks guide).

globalConcurrency?:

number

= 10

Maximum number of background tasks running concurrently across all agents.

perAgentConcurrency?:

number

= 5

Maximum number of background tasks running concurrently for a single agent.

backpressure?:

'queue' | 'reject' | 'fallback-sync'

= 'queue'

Behavior when a concurrency limit is reached. 'queue' waits for a slot, 'reject' throws on enqueue, 'fallback-sync' runs the tool synchronously in the agentic loop instead.

defaultTimeoutMs?:

number

= 300000

Default per-task timeout in milliseconds. Can be overridden per-tool or per-call.

defaultRetries?:

RetryConfig

Default retry policy applied to tasks that fail.

maxRetries?:

number

Maximum retry attempts before the task is marked failed.

retryDelayMs?:

number

Delay between retries in milliseconds.

backoffMultiplier?:

number

Multiplier applied to retryDelayMs on each subsequent attempt.

maxRetryDelayMs?:

number

Upper bound on the retry delay regardless of backoff.

retryableErrors?:

(error: Error) => boolean

Predicate that decides whether a given error should be retried. Default: retry all errors.

cleanup?:

CleanupConfig

Controls how long task records are kept and how often the cleanup process runs.

completedTtlMs?:

number

How long to keep completed task records, in milliseconds. Default: 1 hour.

failedTtlMs?:

number

How long to keep failed task records, in milliseconds. Default: 24 hours.

cleanupIntervalMs?:

number

How often the cleanup process runs, in milliseconds. Default: 1 minute.

waitTimeoutMs?:

number

How long the agentic loop waits for a background task to complete before moving on. If a task has not finished within this time, the loop proceeds without setting isContinued. Default: undefined (do not wait). Can be overridden per-agent or per-tool.

onTaskComplete?:

(task: BackgroundTask) => void | Promise<void>

Global callback invoked when any background task completes successfully. Fires in addition to per-tool and per-agent callbacks.

onTaskFailed?:

(task: BackgroundTask) => void | Promise<void>

Global callback invoked when any background task fails. Fires in addition to per-tool and per-agent callbacks.

deployer

Type: MastraDeployer

Deployment provider for publishing applications to cloud platforms.

Visit the Deployment documentation to learn more.

src/mastra/index.ts

import { Mastra } from '@mastra/core'
import { NetlifyDeployer } from '@mastra/deployer-netlify'

export const mastra = new Mastra({
  deployer: new NetlifyDeployer(),
})

events

Type: Record<string, EventHandler | EventHandler[]>

Event handlers for the internal pub/sub system. Maps event topics to handler functions that are called when events are published to those topics.

注意

This is used internally by Mastra's workflow engine. Most users won't need to configure this option.

src/mastra/index.ts

import { Mastra } from '@mastra/core'

export const mastra = new Mastra({
  events: {
    'my-topic': async event => {
      console.log('Event received:', event)
    },
  },
})

gateways

Type: Record<string, MastraModelGateway>

Custom model router gateways for accessing LLM providers. Gateways handle provider-specific authentication, URL construction, and model resolution. Use this to add support for custom or self-hosted LLM providers.

Visit the Custom Gateways documentation to learn more.

src/mastra/index.ts

import { Mastra } from '@mastra/core'
import { MyPrivateGateway } from './gateways'

export const mastra = new Mastra({
  gateways: {
    private: new MyPrivateGateway(),
  },
})

idGenerator

Type: (context?: IdGeneratorContext) => string
Default: crypto.randomUUID()

Custom ID generator function for creating unique identifiers. Mastra passes optional context so you can generate IDs based on what's being created.

IdGeneratorContext includes:

• idType: 'thread' | 'message' | 'run' | 'step' | 'generic'
• source?: 'agent' | 'workflow' | 'memory'
• entityId?: ID of the requesting agent/workflow/memory entity
• threadId?: Thread ID when relevant (for example, when creating message IDs)
• resourceId?: Resource ID when relevant (for example, user-scoped threads)
• role?: Message role when creating a message ID
• stepType?: Workflow step type when creating a step ID

注意

This is used internally by Mastra for creating IDs for workflow runs, agent conversations, and other resources. Most users won't need to configure this option.

src/mastra/index.ts

import { v4 as uuid } from '@lukeed/uuid'
import { Mastra } from '@mastra/core'

export const mastra = new Mastra({
  idGenerator: context => {
    if (context?.idType === 'message' && context?.threadId) {
      return `msg-${context.threadId}-${uuid()}`
    }

    if (context?.idType === 'run' && context?.source && context?.entityId) {
      return `${context.source}-run-${context.entityId}-${uuid()}`
    }

    return uuid()
  },
})

logger

Type: IMastraLogger | false
Default: ConsoleLogger with INFO level in development, WARN in production

Logger implementation for application logging and debugging. Set to false to disable logging entirely.

Visit the Logging documentation to learn more.

src/mastra/index.ts

import { Mastra } from '@mastra/core'
import { PinoLogger } from '@mastra/loggers'

export const mastra = new Mastra({
  logger: new PinoLogger({ name: 'MyApp', level: 'debug' }),
})

mcpServers

Type: Record<string, MCPServerBase>

MCP (Model Context Protocol) servers that expose Mastra tools, agents, workflows, and resources to MCP-compatible clients. Use this to author your own MCP servers that can be consumed by any system that supports the protocol.

Visit the MCP Overview to learn more.

src/mastra/index.ts

import { Mastra } from '@mastra/core'
import { MCPServer } from '@mastra/mcp'

const mcpServer = new MCPServer({
  id: 'my-mcp-server',
  name: 'My MCP Server',
  version: '1.0.0',
})

export const mastra = new Mastra({
  mcpServers: {
    myServer: mcpServer,
  },
})

memory

Type: Record<string, MastraMemory>

A registry of memory instances that can be referenced by agents, including stored agents that use { type: 'id', memoryId: '<key>' }. Memory gives agents coherence across interactions by retaining relevant information from past conversations. Mastra supports message history for recent messages and working memory for persistent user-specific details. Semantic recall retrieves older messages based on relevance.

Visit the Memory documentation to learn more.

备注

Most users configure memory directly on agents. This top-level configuration is for defining reusable memory instances that can be shared across multiple agents.

src/mastra/index.ts

import { Mastra } from '@mastra/core'
import { Memory } from '@mastra/memory'
import { LibSQLStore } from '@mastra/libsql'

export const mastra = new Mastra({
  storage: new LibSQLStore({
    id: 'mastra-storage',
    url: ':memory:',
  }),
  memory: {
    chatMemory: new Memory({
      options: {
        lastMessages: 20,
      },
    }),
  },
})

observability

Type: ObservabilityEntrypoint

Mastra provides observability features for AI applications. Monitor LLM operations, trace agent decisions, and debug complex workflows with tools that understand AI-specific patterns. Tracing captures model interactions, agent execution paths, tool calls, and workflow steps.

Visit the Observability documentation to learn more.

src/mastra/index.ts

import { Mastra } from '@mastra/core'
import { LibSQLStore } from '@mastra/libsql'
import { Observability, MastraStorageExporter } from '@mastra/observability'

export const mastra = new Mastra({
  storage: new LibSQLStore({
    id: 'mastra-storage',
    url: 'file:./mastra.db',
  }),
  observability: new Observability({
    configs: {
      default: {
        serviceName: 'my-app',
        exporters: [new MastraStorageExporter()],
      },
    },
  }),
})

processors

Type: Record<string, Processor>

Input/output processors for transforming agent inputs and outputs. Processors run at specific points in the agent's execution pipeline, allowing you to modify inputs before they reach the language model or outputs before they're returned. Use processors to add guardrails, detect prompt injection, moderate content, or apply custom business logic.

Visit the Processors documentation to learn more.

备注

Most users configure processors directly on agents. This top-level configuration is for defining reusable processor instances that can be shared across multiple agents.

src/mastra/index.ts

import { Mastra } from '@mastra/core'
import { ModerationProcessor } from '@mastra/core/processors'

export const mastra = new Mastra({
  processors: {
    moderation: new ModerationProcessor({
      model: 'openai/gpt-5-mini',
      categories: ['hate', 'harassment', 'violence'],
    }),
  },
})

pubsub

Type: PubSub
Default: EventEmitterPubSub

Pub/sub system for event-driven communication between components. Used internally by Mastra for workflow event processing and component communication.

注意

This is used internally by Mastra. Most users won't need to configure this option.

src/mastra/index.ts

import { Mastra } from '@mastra/core'
import { CustomPubSub } from './pubsub'

export const mastra = new Mastra({
  pubsub: new CustomPubSub(),
})

scorers

Type: Record<string, Scorer>

Scorers assess the quality of agent responses and workflow outputs. They provide quantifiable metrics for measuring agent quality using model-graded, rule-based, and statistical methods. Use scorers to track performance and compare approaches. They can also identify areas for improvement.

Visit the Scorers documentation to learn more.

备注

Most users configure scorers directly on agents. This top-level configuration is for defining reusable scorer instances that can be shared across multiple agents.

src/mastra/index.ts

import { Mastra } from '@mastra/core'
import { createToxicityScorer } from '@mastra/evals/scorers/prebuilt'

export const mastra = new Mastra({
  scorers: {
    toxicity: createToxicityScorer({ model: 'openai/gpt-5-mini' }),
  },
})

classifiers

Type: Record<string, Classifier>

Classifiers ask decision models fixed-option questions about application state and return typed answers. Register reusable classifiers here to retrieve them with getClassifier() or getClassifierById(). When a registered classifier is evaluated without an active trace, it starts a root CLASSIFIER_EVALUATION span through the Mastra instance's configured observability provider.

Visit the Classifier reference to learn more.

src/mastra/index.ts

import { Mastra } from '@mastra/core'
import { Classifier } from '@mastra/core/classifier'
import { typeSafeAi } from '@ai-sdk/typesafe-ai'

const safety = new Classifier({
  id: 'safety',
  model: typeSafeAi.decisionModel('jev-latest'),
  questions: {
    unsafe: {
      type: 'boolean',
      criteria: { true: 'Unsafe', false: 'Safe' },
    },
  },
})

export const mastra = new Mastra({
  classifiers: { safety },
})

storage

Type: MastraCompositeStore

Storage provider for persisting application data. Used by memory, workflows, traces, and other components that require persistence. Mastra supports multiple database backends including PostgreSQL, MongoDB, libSQL, and more.

Visit the Storage documentation to learn more.

src/mastra/index.ts

import { Mastra } from '@mastra/core'
import { LibSQLStore } from '@mastra/libsql'

export const mastra = new Mastra({
  storage: new LibSQLStore({
    id: 'mastra-storage',
    url: 'file:./mastra.db',
  }),
})

tools

Type: Record<string, Tool>

Tools are reusable functions that agents can use to interact with external systems. Each tool defines inputs, outputs, and execution logic.

Visit the Tools documentation to learn more.

备注

Most users configure tools directly on agents. This top-level configuration is for defining reusable tools that can be shared across multiple agents.

src/mastra/index.ts

import { Mastra } from '@mastra/core'
import { createTool } from '@mastra/core/tools'
import { z } from 'zod'

const weatherTool = createTool({
  id: 'get-weather',
  description: 'Fetches weather for a city',
  inputSchema: z.object({
    city: z.string(),
  }),
  execute: async () => {
    return { temperature: 20, conditions: 'Sunny' }
  },
})

export const mastra = new Mastra({
  tools: {
    weather: weatherTool,
  },
})

tts

Type: Record<string, MastraVoice>

Text-to-speech providers for voice synthesis capabilities. Register voice providers to enable agents to convert text responses into spoken audio.

Visit the Voice documentation to learn more.

备注

Most users configure voice directly on agents. This top-level configuration is for defining reusable voice providers that can be shared across multiple agents.

src/mastra/index.ts

import { Mastra } from '@mastra/core'
import { OpenAIVoice } from '@mastra/voice-openai'

export const mastra = new Mastra({
  tts: {
    openai: new OpenAIVoice(),
  },
})

vectors

Type: Record<string, MastraVector>

Vector stores for semantic search and embeddings. Used in RAG pipelines, similarity search, and other embedding-based features. Mastra supports multiple vector databases including Pinecone, PostgreSQL with pgvector, OracleDB, MongoDB, and more.

Visit the RAG documentation to learn more.

备注

Most users create vector stores directly when building RAG pipelines. This top-level configuration is for defining reusable vector store instances that can be shared across your application.

src/mastra/index.ts

import { Mastra } from '@mastra/core'
import { PineconeVector } from '@mastra/pinecone'

export const mastra = new Mastra({
  vectors: {
    pinecone: new PineconeVector({
      id: 'pinecone-vector',
      apiKey: process.env.PINECONE_API_KEY,
    }),
  },
})

workflows

Type: Record<string, Workflow>

Workflows define step-based execution pipelines with type-safe inputs and outputs. Use workflows for tasks that involve multiple steps with a specific execution order, giving you control over how data flows between steps.

Visit the Workflows documentation to learn more.

src/mastra/index.ts

import { Mastra } from '@mastra/core'
import { testWorkflow } from './workflows/test-workflow'

export const mastra = new Mastra({
  workflows: {
    testWorkflow,
  },
})

workspace

Type: Workspace

A Mastra workspace gives agents a persistent environment for storing files and executing commands. Agents inherit the global workspace on the Mastra class unless they have their own workspace configured.

See the Workspace documentation for implementation details.

src/mastra/index.ts

import { Mastra } from '@mastra/core'
import { Workspace, LocalFilesystem } from '@mastra/core/workspace'

const workspace = new Workspace({
  filesystem: new LocalFilesystem({ basePath: './workspace' }),
})

const mastra = new Mastra({
  workspace,
})

Bundler options

bundler.externals

Type: boolean | string[]
Default: true

When mastra build is run, Mastra bundles your project into the .mastra/output directory. This option controls which packages are excluded from the bundle (marked as "external") and installed separately through a package manager. This is useful when the internal Mastra bundler (Rollup) has trouble bundling packages.

By default, mastra build sets this option to true.

The values have these meanings:

• true: All dependencies listed in your project's package.json are marked as external
• false: No dependencies are marked as external; everything is bundled together
• string[]: An array of package names to mark as external, the rest will be bundled together

src/mastra/index.ts

import { Mastra } from '@mastra/core'

export const mastra = new Mastra({
  bundler: {
    externals: ['some-package', 'another-package'],
  },
})

bundler.sourcemap

Type: boolean
Default: false

Enables source map generation for the bundled output.

src/mastra/index.ts

import { Mastra } from '@mastra/core'

export const mastra = new Mastra({
  bundler: {
    sourcemap: true,
  },
})

bundler.minify

Type: boolean
Default: false

Minifies the bundled output, stripping comments and whitespace and shortening local identifiers. Exported names are preserved.

Off by default so build output stays readable and stack traces stay usable. Enable it when bundle size matters, such as packaging a container image for an on-prem deployment. mastra dev is never minified.

src/mastra/index.ts

import { Mastra } from '@mastra/core'

export const mastra = new Mastra({
  bundler: {
    minify: true,
  },
})

bundler.transpilePackages

Type: string[]
Default: []

List of packages whose source code should be transpiled through esbuild during the build process. Use this for dependencies that contain TypeScript or other code that needs compilation before bundling.

You only need this option if you're importing uncompiled source code directly. If your packages are already compiled to CommonJS or ESM, they don't need to be listed here.

Mastra automatically detects workspace packages in monorepo setups and adds them to this list, so you typically only need to specify external packages that require transpilation.

Mastra also resolves tsconfig.json baseUrl and paths aliases during build. This includes ESM-style imports such as ~/utils/logger.js that point to TypeScript source files.

src/mastra/index.ts

import { Mastra } from '@mastra/core'

export const mastra = new Mastra({
  bundler: {
    transpilePackages: ['@my-org/shared-utils'],
  },
})

bundler.pnpmWorkspaceSettings

Type: Record<string, JSONValue>
Default: {}

Explicit settings to write to the generated pnpm-workspace.yaml when installing deployment dependencies with pnpm. Values can be strings, numbers, booleans, null, arrays, or nested objects. Other package managers ignore this option.

Use this option for pnpm install-policy settings that your deployment install should follow:

src/mastra/index.ts

import { Mastra } from '@mastra/core'

export const mastra = new Mastra({
  bundler: {
    pnpmWorkspaceSettings: {
      blockExoticSubdeps: false,
      minimumReleaseAge: 0,
    },
  },
})

Explicit values override copied source settings. Omitting this option preserves the existing workspace-copy behavior; it doesn't copy all settings from the source workspace.

Only these keys are supported: allowBuilds, onlyBuiltDependencies, ignoredBuiltDependencies, minimumReleaseAge, minimumReleaseAgeExclude, trustPolicy, trustPolicyExclude, trustPolicyIgnoreAfter, and blockExoticSubdeps. Any other key throws an error before pnpm runs, including keys Mastra generates for deployment output (packages, overrides, patchedDependencies, allowUnusedPatches, supportedArchitectures, nodeLinker) and settings that change TLS verification, registries, network access, store integrity, dependency extensions, catalogs, or build-script permissions. neverBuiltDependencies is rejected because pnpm 10 runs every build script it doesn't list. This option doesn't accept command-line flags and isn't a place for secrets.

Explicit allowBuilds and onlyBuiltDependencies values use the same validation as copied source build approvals.

Server options

server.apiRoutes

Type: ApiRoute[]

Mastra automatically exposes registered agents and workflows via its server. For additional behavior you can define your own HTTP routes.

Visit the Custom API routes documentation to learn more.

src/mastra/index.ts

import { Mastra } from '@mastra/core'
import { registerApiRoute } from '@mastra/core/server'

export const mastra = new Mastra({
  server: {
    apiRoutes: [
      registerApiRoute('/my-custom-route', {
        method: 'GET',
        handler: async c => {
          return c.json({ message: 'Custom route' })
        },
      }),
    ],
  },
})

server.auth

Type: MastraAuthConfig | MastraAuthProvider

Authentication configuration for the server. Mastra supports multiple authentication providers including JWT, Clerk, Supabase, Firebase, WorkOS, and Auth0.

Visit the Authentication documentation to learn more.

src/mastra/index.ts

import { Mastra } from '@mastra/core'
import { MastraJwtAuth } from '@mastra/auth'

export const mastra = new Mastra({
  server: {
    auth: new MastraJwtAuth({
      secret: process.env.MASTRA_JWT_SECRET,
      mapUserToResourceId: user => user.id,
    }),
  },
})

The mapUserToResourceId callback maps the authenticated user to a resource ID for memory/thread scoping. When provided, it's called after successful authentication and the returned value is set on the request context as MASTRA_RESOURCE_ID_KEY. When omitted, built-in routes fall back to the client-supplied resource ID (for example memory.resource), so ownership checks trust the caller. Mastra logs a startup warning in that case. See Authorization (User Isolation) for details.

server.bodySizeLimit

Type: number
Default: 4_718_592 (4.5 MB)

Maximum request body size in bytes. Increase this limit if your application needs to handle larger payloads.

src/mastra/index.ts

import { Mastra } from '@mastra/core'

export const mastra = new Mastra({
  server: {
    bodySizeLimit: 10 * 1024 * 1024, // 10mb
  },
})

server.mcpOptions

Type: object
Default: undefined

Options applied to every MCP HTTP route. MCP requests are self-contained, so no session state is kept between them and the routes run unchanged in serverless environments (Cloudflare Workers, Vercel Edge, AWS Lambda, etc.).

Property	Type	Default	Description
setRequestAuth	(req, requestContext) => void | Promise<void>	undefined	Sets req.auth on the request handed to the MCP transport, which surfaces as context.mcp.extra.authInfo in tools. When omitted, the principal resolved by server.auth is bridged automatically.
serverless	boolean	false	Accepted for compatibility. Has no effect: every MCP request is already stateless.
sessionIdGenerator	() => string	undefined	Accepted for compatibility. Has no effect: MCP requests carry no session.

src/mastra/index.ts

import { Mastra } from '@mastra/core'

export const mastra = new Mastra({
  server: {
    mcpOptions: {
      setRequestAuth: (req, requestContext) => {
        const payload = requestContext.get('bearerPayload')
        req.auth = { token: payload.token, clientId: payload.sub, scopes: [] }
      },
    },
  },
})

server.build

Build-time configuration for server features. These options control development tools like Swagger UI and request logging, which are enabled during local development but disabled in production by default.

Property	Type	Default	Description
swaggerUI	boolean	false	Enable Swagger UI at /swagger-ui for interactive API exploration (requires openAPIDocs to be true)
apiReqLogs	boolean	false	Enable API request logging to the console
openAPIDocs	boolean	false	Enable OpenAPI specification at /api/openapi.json. Built-in Mastra routes use servers: [{url: "/api"}] while custom routes get a per-path servers: [{url: "/"}] override.

src/mastra/index.ts

import { Mastra } from '@mastra/core'

export const mastra = new Mastra({
  server: {
    build: {
      swaggerUI: true,
      apiReqLogs: true,
      openAPIDocs: true,
    },
  },
})

server.cors

Type: CorsOptions | false

CORS (Cross-Origin Resource Sharing) configuration for the server. Set to false to disable CORS entirely. Use this for one policy across all routes. For a custom route-specific policy, use the cors option in registerApiRoute().

Property	Type	Default	Description
origin	string | string[]	'*'	Origins for CORS requests
allowMethods	string[]	['GET', 'POST', 'PUT', 'PATCH', 'DELETE', 'OPTIONS']	HTTP methods
allowHeaders	string[]	['Content-Type', 'Authorization', 'x-mastra-client-type', 'x-mastra-dev-playground']	Request headers
exposeHeaders	string[]	['Content-Length', 'X-Requested-With']	Browser headers
credentials	boolean	false	Credentials (cookies, authorization headers)
maxAge	number	3600	Preflight request cache duration in seconds

src/mastra/index.ts

import { Mastra } from '@mastra/core'

export const mastra = new Mastra({
  server: {
    cors: {
      origin: ['https://example.com'],
      allowMethods: ['GET', 'POST', 'PUT', 'DELETE', 'OPTIONS'],
      allowHeaders: ['Content-Type', 'Authorization'],
      credentials: false,
    },
  },
})

server.handleShutdownSignals

Type: boolean
Default: true

Whether the server generated by mastra dev and mastra build installs its own SIGINT/SIGTERM handlers. By default, receiving a signal begins graceful shutdown. The generated server stops accepting new connections and drains in-flight requests before it runs mastra.shutdown() and exits the process (see server.drainTimeout).

Set handleShutdownSignals: false to manage signals yourself, for example with a handler registered in your Mastra config module that calls mastra.shutdown():

src/mastra/index.ts

import { Mastra } from '@mastra/core'

export const mastra = new Mastra({
  server: {
    handleShutdownSignals: false,
  },
})

let shuttingDown = false
const shutdown = async () => {
  if (shuttingDown) return
  shuttingDown = true
  // custom shutdown coordination
  await mastra.shutdown()
  process.exit(0)
}

process.once('SIGINT', shutdown)
process.once('SIGTERM', shutdown)

Be aware of these caveats:

• Without a handler of your own, Node.js default signal behavior applies: the process terminates immediately with no drain.
• Your handler has no access to the HTTP server handle in the generated entry file, so it can't drain in-flight HTTP requests. If you only need a longer drain window, prefer server.drainTimeout. For full control over the server lifecycle, use a server adapter.
• During mastra dev, the built-in handlers release storage resources between hot reloads (for example, DuckDB file locks). Disabling them without an equivalent handler can cause lock conflicts after a reload.

server.host

Type: string
Default: localhost (or MASTRA_HOST environment variable if set)

Host address the Mastra development server binds to. If the MASTRA_HOST environment variable is set, it takes precedence over the default.

src/mastra/index.ts

import { Mastra } from '@mastra/core'

export const mastra = new Mastra({
  server: {
    host: '0.0.0.0',
  },
})

server.https

Type: { key: Buffer; cert: Buffer }

HTTPS configuration for running the development server with TLS. Mastra supports local HTTPS development through the mastra dev --https flag, which automatically creates and manages certificates. For custom certificate management, provide your own key and certificate files:

src/mastra/index.ts

import { Mastra } from '@mastra/core'
import fs from 'node:fs'

export const mastra = new Mastra({
  server: {
    https: {
      key: fs.readFileSync('path/to/key.pem'),
      cert: fs.readFileSync('path/to/cert.pem'),
    },
  },
})

server.middleware

Type: Middleware | Middleware[]

Custom middleware functions to intercept requests before or after route handlers. Middleware can be used for authentication, logging, injecting request-specific context, or adding headers. Each middleware receives the Hono Context and a next function. Return a Response to short-circuit the request, or call next() to continue processing.

Visit the Middleware documentation to learn more.

src/mastra/index.ts

import { Mastra } from '@mastra/core'

export const mastra = new Mastra({
  server: {
    middleware: [
      {
        handler: async (c, next) => {
          const authHeader = c.req.header('Authorization')
          if (!authHeader) {
            return new Response('Unauthorized', { status: 401 })
          }
          await next()
        },
        path: '/api/*',
      },
    ],
  },
})

server.onError

Type: (err: Error, c: Context) => Response | Promise<Response>

Custom error handler called when an unhandled error occurs. Use this to customize error responses or log errors to external services such as Sentry. You can also implement custom error formatting.

This hook is supported by all server adapters. The c parameter provides a Hono-compatible context object: for non-Hono adapters (Koa, Express, Fastify), a shim is provided with commonly used methods like c.json() and c.req.path.

src/mastra/index.ts

import { Mastra } from '@mastra/core'
import * as Sentry from '@sentry/node'

export const mastra = new Mastra({
  server: {
    onError: (err, c) => {
      Sentry.captureException(err)

      return c.json(
        {
          error: err.message,
          timestamp: new Date().toISOString(),
        },
        500,
      )
    },
  },
})

server.onValidationError

Type: (error: ZodError, context: 'query' | 'body' | 'path') => { status: number; body: unknown } | undefined

Custom handler called when a request fails Zod schema validation. Use this to customize validation error responses and change the status code, or to format errors to match your API standards.

Return a { status, body } object to override the default 400 response, or undefined to use the default behavior. This hook is supported by all server adapters (Hono, Express, Fastify, Koa).

The context parameter indicates which part of the request failed validation:

• 'query': query parameters
• 'body': request body
• 'path': path parameters

src/mastra/index.ts

import { Mastra } from '@mastra/core'

export const mastra = new Mastra({
  server: {
    onValidationError: (error, context) => ({
      status: 422,
      body: {
        ok: false,
        errors: error.issues.map(i => ({
          path: i.path.join('.'),
          message: i.message,
        })),
        source: context,
      },
    }),
  },
})

You can also set onValidationError on individual routes created with createRoute(). A route-level hook takes precedence over the server-level hook.

server.port

Type: number
Default: 4111 (or PORT environment variable if set)

Port the Mastra development server binds to. If the PORT environment variable is set, it takes precedence over the default.

src/mastra/index.ts

import { Mastra } from '@mastra/core'

export const mastra = new Mastra({
  server: {
    port: 8080,
  },
})

server.drainTimeout

Type: number
Default: 5000 (5 seconds)

Maximum time in milliseconds to drain in-flight requests after the server receives SIGINT or SIGTERM. The value must be finite and between 0 and 2147483647. During this window the server stops accepting new connections and waits for in-flight requests (including active streams) to finish; if the deadline passes first, remaining HTTP connections are closed. Upgraded connections such as WebSockets end when the process exits. Either way, mastra.shutdown({ drainTimeout }) then runs before the process exits. It gives in-flight workflow runs (including durable agent runs) the same window to reach a finished or suspended state before workers and pub/sub subscriptions are torn down. Background task cancellation and worker teardown share that window. The generated server then allows up to 5 seconds for workspace and storage cleanup. Setting 0 skips both drains.

Increase this when rolling deploys need to let long-running agent turns or workflow steps finish. The HTTP drain and the workflow drain run one after the other. Plan for a worst case of twice this value plus 5 seconds of cleanup and keep that total below your platform's grace period (for example terminationGracePeriodSeconds on Kubernetes):

src/mastra/index.ts

import { Mastra } from '@mastra/core'

export const mastra = new Mastra({
  server: {
    drainTimeout: 600000, // 10 minutes
  },
})

Sending either shutdown signal again during the drain bypasses it and terminates the process immediately.

server.studioBase

Type: string
Default: /

Base path for hosting Studio. Use this to host the Studio on a sub-path of your existing application instead of the root.

This is useful when integrating with existing applications or authentication tools such as Cloudflare Zero Trust that benefit from shared domains. It also supports managing multiple services under one domain.

src/mastra/index.ts

import { Mastra } from '@mastra/core'

export const mastra = new Mastra({
  server: {
    studioBase: '/my-mastra-studio',
  },
})

Example URLs:

• Default: http://localhost:4111/ (studio at root)
• With studioBase: http://localhost:4111/my-mastra-studio/ (studio at sub-path)

server.timeout

Type: number
Default: 180000 (3 minutes)

Request timeout in milliseconds. Requests that exceed this duration will be terminated.

src/mastra/index.ts

import { Mastra } from '@mastra/core'

export const mastra = new Mastra({
  server: {
    timeout: 30000, // 30 seconds
  },
})