mastra-config.mdx

Mastra’s configuration file is a ts file that exports a Config object. Here’s the structure:

Project Configuration

Key Fields

Name

name: string - The name of your Mastra project.

Other fields

systemHostURL (optional): string - Mastra uses this when it’s creating OAuth connection strings. Defaults to process.env.APP_URL.
routeRegistrationPath (optional): string - Mastra puts a templated route.js folder in your app at this path that works with Next.js to handle. Defaults to /api/mastra.

Database Configuration

Mastra needs a database to store the state of the system: authentication credentials and synced records. Mastra supports any database that Drizzle does.

db: object - Database configuration.
- provider: ‘postgres’ - The database provider.
- uri: string - The connection URI for your database.

When you deploy, we recommend setting uri to an environment variable so that you can have different values for production and development.

Runner Configuration

Mastra uses Inngest to run background jobs, like refreshing credentials and syncing records.

runner: object - The runner configuration.
- provider: ‘inngest’ - The runner provider.
- uri: string - The connection URI for your runner.

When you deploy, we recommend setting uri to an environment variable so that you can have different values for production and development.

Agents Configuration

interface AgentsConfig {
  agentDirPath: string;      // Path to agent configuration directory
  vectorProvider: VectorProvider[];  // Vector store configurations
}
 
interface VectorProvider {
  name: 'PINECONE';          // Vector store provider name
  apiKey: string;            // Provider API key
  dirPath?: string;          // Optional: Custom directory path for provider configs
}

Required Fields

agentDirPath: Directory where agent configurations are stored
vectorProvider: Array of vector store providers
- name: Provider name (currently supports ‘PINECONE’)
- apiKey: Authentication key for the provider

Optional Fields

vectorProvider[].dirPath: Custom path for provider-specific configurations

Example

mastra.config.ts

export const config: Config = {
  agents: {
    agentDirPath: '/mastra-agents',
    vectorProvider: [
      {
        name: 'PINECONE',
        apiKey: process.env.PINECONE_API_KEY!,
        dirPath: '/custom/vector/path'
      },
    ],
  },
}

Environment Variables

PINECONE_API_KEY: Your Pinecone API key
MASTRA_APP_DIR: Optional: Override for application directory

For detailed vector store configuration, see the Vector Store Configuration documentation.

Workflow Configuration

Workflows consume events and trigger actions. Your system will define the events that can trigger workflows, and you can also consume events from external systems.

workflows: object - Workflow configuration.
- systemEvents: Record<string, SystemEvent> - An object defining events that happen in your app that you want to trigger workflows from.
- blueprintDirPath: string - The directory path for storing blueprints (defaults to /mastra/blueprints).
- systemApis: SystemApis[] - An array of system-level apis.

Integration Configuration

integrations: Integration[] - An array of integration instances to be used in your project.

Integrations have to be individually installed, authenticated, and imported in the mastra.config.ts file. If you use the admin app, it will help you with the process.

The integration config object will vary depending on the authentication type of the integration:

OAuth-based integrations will have CLIENT_ID, CLIENT_SECRET, and SCOPES as required fields.
API key-based integrations will have API_KEY as a required field.
Basic auth-based integrations will have USERNAME and PASSWORD as required fields.

Integrations can also define additional required or optional fields. Look at the package README for additional details.

Mastra CLI getAgent