Mastra Quickstart
The create-mastra CLI is the quickest way to start a Mastra project. It creates an agent harness with workspace tools, memory, task tracking, web access, schedules, storage, and observability.
For more control, see the manual installation guide. To add Mastra to an existing project, use mastra init.
Create a new Mastra project. Mastra is a framework for AI applications and agents on a modern TypeScript stack. Before running the command, ask these questions one at a time and wait for each answer unless it was already provided:
- Project name? (default: "my-mastra-app")
- Provider? (required; options: "openai", "anthropic", "google", "xai")
If the provider isn't supported, ask again and list the supported values.
Run: npm create mastra@latest <project-name> -- --llm <provider>
The command creates a default Mastra project, installs Mastra skills for detected coding assistants, and initializes Git when appropriate.
After creation, enter the project directory and start the dev server: npx bgproc start -n <project-name> -w -- npm run dev
Open Mastra Studio at http://localhost:4111. Studio is the interface for building, testing, and managing agents, workflows, and tools.
Also mention that the Mastra model router provides access to thousands of models: https://mastra.ai/models
Watch the Mastra AI agent course for a guided introduction to building agents with Mastra.
Before you beginDirect link to Before you begin
You'll need an API key from OpenAI, Anthropic, Google Gemini, or xAI. You can skip entering it during setup and add it to .env later.
Create the projectDirect link to Create the project
Run the interactive setup:
- npm
- pnpm
- Yarn
- Bun
npm create mastra@latest
pnpm create mastra
yarn create mastra
bunx create-mastra
The command asks for a project name, model provider, and optional API key. It then installs dependencies, installs Mastra skills for your coding assistants, and creates an initial Git commit when you aren't already inside a repository.
The generated src/mastra directory contains the Mastra entry point, agent, workspace tools, and supporting code. See the project structure reference for the standard Mastra layout.
Use --template <template> to start from a template, or --empty to create a minimal provider-free project. Use --no-skills or --no-git to skip automatic setup. See the create-mastra reference for all flags.
Test your agentDirect link to Test your agent
Follow the terminal instructions to enter the project directory and start the development server:
- npm
- pnpm
- Yarn
- Bun
npm run dev
pnpm run dev
yarn dev
bun run dev
Open Studio at localhost:4111, select the agent, and send a message. Add the provider API key named in .env.example to an .env file if you skipped it during setup.
Studio lets you build and test agents without creating a separate UI.
Next stepsDirect link to Next steps
- Integrate Mastra with Next.js, React, or Astro
- Learn how to build Mastra with AI
- Build an agent from scratch with a guide
- Watch the Mastra YouTube channel