Install Mastra

The create mastra CLI command is the quickest way to start a new Mastra project. It walks you through setup and creates example agents, workflows, and tools for you to learn from or adapt.

For more control over setup, or to add Mastra to an existing project, see the manual installation guide. You can also use mastra init for existing projects.

Before you start

You’ll need an API key from a large language model provider to complete setup. We recommend starting with Gemini , as you likely already have a Google account and they don’t require a card.
Node.js 20 or later.

Install with `create mastra`

You can run create mastra anywhere on your machine.

The wizard will guide you through setup, create a new directory for your project, and generate a weather agent with example workflows and tools to get you started.


npm create mastra@latest -y


pnpm create mastra@latest -y


yarn create mastra@latest -y


bun create mastra@latest -y

You can use flags with create mastra like --no-example to skip the example weather agent or --template to start from a specific template. Read the CLI reference for all options.

Test your agent

Once setup is complete, follow the instructions in your terminal to start the Mastra dev server, then open the Playground at http://localhost:4111 .

Try asking about the weather. If your API key is set up correctly, you’ll get a response:

If you encounter an error, your API key may not be configured correctly. Double-check your setup and try again. Need more help? Join our Discord and talk to the team directly.

The Playground lets you rapidly build and prototype agents without needing to build a UI. Once you’re ready, you can integrate your Mastra agent into your application using the guides below.

Next steps

Integrate Mastra with your frontend framework: Next.js, React, or Astro
Build an agent from scratch following one of our guides
Read more about Mastra’s features
Watch conceptual guides on our YouTube channel and subscribe

Install manually

If you prefer not to use our automatic create mastra CLI tool, you can set up your project yourself by following the guide below.

Create a new project

Create a new project and change directory:


mkdir hello-mastra && cd hello-mastra

Initialize a TypeScript project including the @mastra/core package:


npm init -y
 
npm install typescript tsx @types/node mastra@latest --save-dev
 
npm install @mastra/core@latest zod@^3 @ai-sdk/openai@^1


pnpm init
 
pnpm add typescript tsx @types/node mastra@latest --save-dev
 
pnpm add @mastra/core@latest zod@^3 @ai-sdk/openai@^1


yarn init -y
 
yarn add typescript tsx @types/node mastra@latest --dev
 
yarn add @mastra/core@latest zod@^3 @ai-sdk/openai@^1


bun init -y
 
bun add typescript tsx @types/node mastra@latest --dev
 
bun add @mastra/core@latest zod@^3 @ai-sdk/openai@^1

Add the dev and build scripts to package.json:

package.json


{
  "scripts": {
    // ...
    "dev": "mastra dev",
    "build": "mastra build"
  }
}

Initialize TypeScript

Create a tsconfig.json file:


touch tsconfig.json

Add the following configuration:

Mastra requires module and moduleResolution values that support modern Node.js versions. Older settings like CommonJS or node are incompatible with Mastra’s packages and will cause resolution errors.

tsconfig.json


{
  "compilerOptions": {
    "target": "ES2022",
    "module": "ES2022",
    "moduleResolution": "bundler",
    "esModuleInterop": true,
    "forceConsistentCasingInFileNames": true,
    "strict": true,
    "skipLibCheck": true,
    "noEmit": true,
    "outDir": "dist"
  },
  "include": [
    "src/**/*"
  ]
}

This TypeScript configuration is optimized for Mastra projects, using modern module resolution and strict type checking.

Set up your API key

Create .env file:


touch .env

Add your API key:

.env


OPENAI_API_KEY=<your-api-key>

This example uses OpenAI. Each LLM provider uses a unique name. See Model Capabilities for more information.

Create a Tool

Create a weather-tool.ts file:


mkdir -p src/mastra/tools && touch src/mastra/tools/weather-tool.ts

Add the following code:

src/mastra/tools/weather-tool.ts


import { createTool } from "@mastra/core/tools";
import { z } from "zod";
 
export const weatherTool = createTool({
  id: "get-weather",
  description: "Get current weather for a location",
  inputSchema: z.object({
    location: z.string().describe("City name")
  }),
  outputSchema: z.object({
    output: z.string()
  }),
  execute: async () => {
    return {
      output: "The weather is sunny"
    };
  }
});

See the full weatherTool example in Giving an Agent a Tool.

Create an Agent

Create a weather-agent.ts file:


mkdir -p src/mastra/agents && touch src/mastra/agents/weather-agent.ts

Add the following code:

src/mastra/agents/weather-agent.ts


import { openai } from "@ai-sdk/openai";
import { Agent } from "@mastra/core/agent";
import { weatherTool } from "../tools/weather-tool";
 
export const weatherAgent = new Agent({
  name: 'Weather Agent',
  instructions: `
      You are a helpful weather assistant that provides accurate weather information.
 
      Your primary function is to help users get weather details for specific locations. When responding:
      - Always ask for a location if none is provided
      - If the location name isn’t in English, please translate it
      - If giving a location with multiple parts (e.g. "New York, NY"), use the most relevant part (e.g. "New York")
      - Include relevant details like humidity, wind conditions, and precipitation
      - Keep responses concise but informative
 
      Use the weatherTool to fetch current weather data.
`,
  model: openai('gpt-4o-mini'),
  tools: { weatherTool }
});

Register the Agent

Create the Mastra entry point and register agent:


touch src/mastra/index.ts

Add the following code:

src/mastra/index.ts


import { Mastra } from "@mastra/core/mastra";
import { weatherAgent } from "./agents/weather-agent";
 
export const mastra = new Mastra({
  agents: { weatherAgent }
});

You can now launch the Mastra Development Server and test your agent using the Mastra Playground.

Add to an existing project

Mastra can be installed and integrated into a wide range of projects. Below are links to integration guides to help you get started:

`mastra init`

To install Mastra in an existing project, use the mastra init command.

See mastra init for more information.

Next steps

Install Mastra

The create mastra CLI command is the quickest way to start a new Mastra project. It walks you through setup and creates example agents, workflows, and tools for you to learn from or adapt.

For more control over setup, or to add Mastra to an existing project, see the manual installation guide. You can also use mastra init for existing projects.

Before you start

You’ll need an API key from a large language model provider to complete setup. We recommend starting with Gemini , as you likely already have a Google account and they don’t require a card.
Node.js 20 or later.

Install with `create mastra`

You can run create mastra anywhere on your machine.

The wizard will guide you through setup, create a new directory for your project, and generate a weather agent with example workflows and tools to get you started.


npm create mastra@latest -y


pnpm create mastra@latest -y


yarn create mastra@latest -y


bun create mastra@latest -y

You can use flags with create mastra like --no-example to skip the example weather agent or --template to start from a specific template. Read the CLI reference for all options.

Test your agent

Once setup is complete, follow the instructions in your terminal to start the Mastra dev server, then open the Playground at http://localhost:4111 .

Try asking about the weather. If your API key is set up correctly, you’ll get a response:

If you encounter an error, your API key may not be configured correctly. Double-check your setup and try again. Need more help? Join our Discord and talk to the team directly.

The Playground lets you rapidly build and prototype agents without needing to build a UI. Once you’re ready, you can integrate your Mastra agent into your application using the guides below.

Next steps

Integrate Mastra with your frontend framework: Next.js, React, or Astro
Build an agent from scratch following one of our guides
Read more about Mastra’s features
Watch conceptual guides on our YouTube channel and subscribe

Install manually

If you prefer not to use our automatic create mastra CLI tool, you can set up your project yourself by following the guide below.

Create a new project

Create a new project and change directory:


mkdir hello-mastra && cd hello-mastra

Initialize a TypeScript project including the @mastra/core package:


npm init -y
 
npm install typescript tsx @types/node mastra@latest --save-dev
 
npm install @mastra/core@latest zod@^3 @ai-sdk/openai@^1


pnpm init
 
pnpm add typescript tsx @types/node mastra@latest --save-dev
 
pnpm add @mastra/core@latest zod@^3 @ai-sdk/openai@^1


yarn init -y
 
yarn add typescript tsx @types/node mastra@latest --dev
 
yarn add @mastra/core@latest zod@^3 @ai-sdk/openai@^1


bun init -y
 
bun add typescript tsx @types/node mastra@latest --dev
 
bun add @mastra/core@latest zod@^3 @ai-sdk/openai@^1

Add the dev and build scripts to package.json:

package.json


{
  "scripts": {
    // ...
    "dev": "mastra dev",
    "build": "mastra build"
  }
}

Initialize TypeScript

Create a tsconfig.json file:


touch tsconfig.json

Add the following configuration:

tsconfig.json


{
  "compilerOptions": {
    "target": "ES2022",
    "module": "ES2022",
    "moduleResolution": "bundler",
    "esModuleInterop": true,
    "forceConsistentCasingInFileNames": true,
    "strict": true,
    "skipLibCheck": true,
    "noEmit": true,
    "outDir": "dist"
  },
  "include": [
    "src/**/*"
  ]
}

This TypeScript configuration is optimized for Mastra projects, using modern module resolution and strict type checking.

Set up your API key

Create .env file:


touch .env

Add your API key:

.env


OPENAI_API_KEY=<your-api-key>

This example uses OpenAI. Each LLM provider uses a unique name. See Model Capabilities for more information.

Create a Tool

Create a weather-tool.ts file:


mkdir -p src/mastra/tools && touch src/mastra/tools/weather-tool.ts

Add the following code:

src/mastra/tools/weather-tool.ts


import { createTool } from "@mastra/core/tools";
import { z } from "zod";
 
export const weatherTool = createTool({
  id: "get-weather",
  description: "Get current weather for a location",
  inputSchema: z.object({
    location: z.string().describe("City name")
  }),
  outputSchema: z.object({
    output: z.string()
  }),
  execute: async () => {
    return {
      output: "The weather is sunny"
    };
  }
});

See the full weatherTool example in Giving an Agent a Tool.

Create an Agent

Create a weather-agent.ts file:


mkdir -p src/mastra/agents && touch src/mastra/agents/weather-agent.ts

Add the following code:

src/mastra/agents/weather-agent.ts


import { openai } from "@ai-sdk/openai";
import { Agent } from "@mastra/core/agent";
import { weatherTool } from "../tools/weather-tool";
 
export const weatherAgent = new Agent({
  name: 'Weather Agent',
  instructions: `
      You are a helpful weather assistant that provides accurate weather information.
 
      Your primary function is to help users get weather details for specific locations. When responding:
      - Always ask for a location if none is provided
      - If the location name isn’t in English, please translate it
      - If giving a location with multiple parts (e.g. "New York, NY"), use the most relevant part (e.g. "New York")
      - Include relevant details like humidity, wind conditions, and precipitation
      - Keep responses concise but informative
 
      Use the weatherTool to fetch current weather data.
`,
  model: openai('gpt-4o-mini'),
  tools: { weatherTool }
});

Register the Agent

Create the Mastra entry point and register agent:


touch src/mastra/index.ts

Add the following code:

src/mastra/index.ts


import { Mastra } from "@mastra/core/mastra";
import { weatherAgent } from "./agents/weather-agent";
 
export const mastra = new Mastra({
  agents: { weatherAgent }
});

You can now launch the Mastra Development Server and test your agent using the Mastra Playground.

Add to an existing project

Mastra can be installed and integrated into a wide range of projects. Below are links to integration guides to help you get started:

`mastra init`

To install Mastra in an existing project, use the mastra init command.

See mastra init for more information.

Install Mastra

Before you start

Install with create mastra

Test your agent

Next steps

Install manually

Create a new project

Initialize TypeScript

Set up your API key

Create a Tool

Create an Agent

Register the Agent

Add to an existing project

mastra init

Next steps

Install Mastra

Before you start

Install with create mastra

Test your agent

Next steps

Install manually

Create a new project

Initialize TypeScript

Set up your API key

Create a Tool

Create an Agent

Register the Agent

Add to an existing project

mastra init

Next steps

Install with `create mastra`

`mastra init`

Install with `create mastra`

`mastra init`