Getting Started with Mastra

The create mastra CLI command is the quickest way to get started. It walks you through setup and creates example agents, workflows, and tools for you to run locally or adapt.

If you need more control over the setup, see the manual installation guide. You can also use mastra init for existing projects.

Create New Mastra Project

Make new Mastra project. Mastra = framework for AI apps + agents on modern TypeScript stack. Before run command, ask these questions one by one. Wait for answers unless already given:

  1. Project name? (default: "my-mastra-app")
  2. Provider? (default: "openai", options: "openai", "anthropic", "groq", "google", "cerebras", "mistral")

Provider Rules:

  • Allowed provider -> use it.
  • Any other value -> use "openai".

Run with answers: npm create mastra@latest <project-name> --default --llm <provider>

After project created, go to project dir. Start dev server: npx bgproc start -n <project-name> -w -- npm run dev

Start Mastra Studio at http://localhost:4111. Studio = UI for build, test, manage agents, workflows, tools.

Mastra model router gives 3000+ models from many providers: Mastra Models

Before You Begin

  • You'll need an API key from a supported model provider. If you don't have a preference, use OpenAI.

Initialize Mastra

You can run create mastra anywhere on your machine.

When prompted, choose a provider (e.g. OpenAI) and enter your key:

npm create mastra@latest

pnpm create mastra

yarn create mastra

bunx create-mastra

This creates a new directory for your project with a src/mastra folder containing an example weather agent and the following files:

  • index.ts: Entry point for all Mastra-related code and configuration
  • agents/weather-agent.ts: A weather agent with a prompt that uses the tool
  • tools/weather-tool.ts: A tool to fetch weather for a given location
  • workflows/weather-workflow.ts: A workflow that runs the weather agent
  • scorers/weather-scorer.ts: A scorer to evaluate the weather agent's responses

Depending on your choices, you'll also end up with Mastra Skills or the MCP Docs Server installed.

You can use flags with create mastra like --no-example to skip the example weather agent or --template to start from a specific template.

Test Your Agent

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

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

Studio 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 app using the guides below.

Next Steps