---
title: "Quickstart"
description: Get started with Mastra using the create mastra CLI to build a server with agents, workflows, and tools.
---

import Tabs from "@theme/Tabs";
import TabItem from "@theme/TabItem";
import Steps from "@site/src/components/Steps";
import StepItem from "@site/src/components/StepItem";
import { VideoPlayer } from "@site/src/components/video-player";

# Mastra Quickstart

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](/docs/v1/getting-started/manual-install). You can also use [`mastra init`](/reference/v1/cli/mastra#mastra-init) for existing projects.

## Before you begin

* You'll need an API key from a supported [model provider](/models/v1). If you don't have a preference, use [OpenAI](/models/v1/providers/openai).

## Initialize Mastra

You can run `create mastra` anywhere on your machine.

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

<Tabs>
<TabItem value="npm" label="npm">

```bash
npm create mastra@beta
```

</TabItem>
<TabItem value="pnpm" label="pnpm">

```bash
pnpm create mastra@beta
```

</TabItem>
<TabItem value="yarn" label="yarn">

```bash
yarn create mastra@beta
```

</TabItem>
<TabItem value="bun" label="bun">

```bash
bun create mastra@beta
```

:::warning

Due to a [known issue with Bun](https://github.com/oven-sh/bun/issues/25314) you'll need to run these steps after creating the project:

- `bun add @mastra/server@beta`
- Delete your `node_modules` folder
- Delete your `bun.lock` file
- Run `bun install` to reinstall your packages

:::

</TabItem>
</Tabs>

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

- `index.ts` - Mastra config, including memory
- `tools/weather-tool.ts` - a tool to fetch weather for a given location
- `agents/weather-agent.ts` - a weather agent with a prompt that uses the tool

:::tip

You can use [flags](/reference/v1/cli/create-mastra#cli-flags) with `create mastra` like `--no-example` to skip the example weather agent or `--template` to start from a specific [template](https://mastra.ai/templates).

:::

## 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](http://localhost:4111).

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

<VideoPlayer src="https://res.cloudinary.com/mastra-assets/video/upload/v1751406022/local-dev-agents-playground_100_m3begx.mp4" />

[Studio](/docs/v1/getting-started/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

- Integrate Mastra with your frontend framework: [Next.js](/guides/v1/getting-started/next-js), [React](/guides/v1/getting-started/vite-react), or [Astro](/guides/v1/getting-started/astro)
- Read more about [Mastra's features](/docs/v1#why-mastra)
- Build an agent from scratch following one of our [guides](/guides/v1)
- Watch conceptual guides on our [YouTube channel](https://www.youtube.com/@mastra-ai) and [subscribe](https://www.youtube.com/@mastra-ai?sub_confirmation=1)
