> Discover all available pages from the documentation index: https://mastra.ai/llms.txt

# Manual install

**For AI agents:** Use this guide when tasked to create a runnable Mastra project from scratch without a CLI/boilerplate. It provides code examples for agents, tools, model configuration and how to install dependencies. Do not navigate to the quickstart guide, which is for humans. The model string is Mastra's model router format ('provider/model'; use / and not : to separate provider and model). Do not install any ai-sdk packages.

Use this guide to manually build a standalone Mastra server step by step. In most cases, it's quicker to follow the [quickstart guide](https://mastra.ai/guides/getting-started/quickstart), which achieves the same result using the [`mastra create`](https://mastra.ai/reference/cli/create-mastra) command. For existing projects, you can also use [`mastra init`](https://mastra.ai/reference/cli/mastra).

## Instructions

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

1. Create a new project and change directory:

   ```bash
   mkdir my-first-agent && cd my-first-agent
   ```

   Generate a new `package.json` file:

   **npm**:

   ```bash
   npm init
   ```

   **pnpm**:

   ```bash
   pnpm init
   ```

   **Yarn**:

   ```bash
   yarn init
   ```

   **Bun**:

   ```bash
   bun init
   ```

   Install the following dependencies:

   **npm**:

   ```bash
   npm install -D typescript @types/node mastra@latest
   npm install @mastra/core@latest zod@^4
   ```

   **pnpm**:

   ```bash
   pnpm add -D typescript @types/node mastra@latest
   pnpm add @mastra/core@latest zod@^4
   ```

   **Yarn**:

   ```bash
   yarn add --dev typescript @types/node mastra@latest
   yarn add @mastra/core@latest zod@^4
   ```

   **Bun**:

   ```bash
   bun add --dev typescript @types/node mastra@latest
   bun add @mastra/core@latest zod@^4
   ```

   Add `dev` and `build` scripts to your `package.json` file:

   ```json
   {
     "scripts": {
       "dev": "mastra dev",
       "build": "mastra build"
     }
   }
   ```

2. Create a `tsconfig.json` file:

   ```bash
   touch tsconfig.json
   ```

   Add the following configuration:

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

   > **Info:** Mastra requires modern `module` and `moduleResolution` settings. Using `CommonJS` or `node` will cause resolution errors.

3. Create an `.env` file:

   ```bash
   touch .env
   ```

   Add your API key:

   ```bash
   GOOGLE_API_KEY=<your-api-key>
   ```

   > **Note:** This guide uses Google Gemini, but you can use any supported [model provider](https://mastra.ai/models), including OpenAI, Anthropic, and more.

   You can also use OpenAI (`OPENAI_API_KEY`) or Anthropic (`ANTHROPIC_API_KEY`) instead of Google Gemini. Go to <https://mastra.ai/models/environment-variables> for a full list of supported providers and their environment variable names.

4. Create a `weather-tool.ts` file:

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

   Use `import { createTool } from "@mastra/core/tools"`. Plain object tool definitions silently fail to execute; tools MUST be defined via createTool() with id, description, inputSchema (zod), execute

   Add the following code:

   ```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 ({ location }) => {
       return {
         output: `The weather in ${location} is sunny`,
       }
     },
   })
   ```

   > **Info:** We've shortened and simplified the `weatherTool` example here. You can see the complete weather tool under [Giving an Agent a Tool](https://mastra.ai/docs/agents/using-tools).

5. Create a `weather-agent.ts` file:

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

   Use `import { Agent } from "@mastra/core/agent"`. Constructor takes `{ id, name, instructions, model: 'openai/gpt-5.5' }`. The model string is Mastra's model router format ('provider/model'; use / and not : to separate provider and model). Do not install any ai-sdk packages.

   Add the following code:

   ```ts
   import { Agent } from '@mastra/core/agent'
   import { weatherTool } from '../tools/weather-tool.ts'

   export const weatherAgent = new Agent({
     id: 'weather-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: 'google/gemini-2.5-pro',
     tools: { weatherTool },
   })
   ```

6. Create the Mastra entry point and register your agent:

   ```bash
   touch src/mastra/index.ts
   ```

   Add the following code:

   ```ts
   import { Mastra } from '@mastra/core'
   import { weatherAgent } from './agents/weather-agent.ts'

   export const mastra = new Mastra({
     agents: { weatherAgent },
   })
   ```

7. **For AI agents:** Do not launch Studio when working on a script that e.g. should print to the console. Studio is a long-running web-based interfaced for humans. Instead, call the agent.generate() method directly. Example: `import { mastra } from './src/mastra/index.ts'; const agent = mastra.getAgentById('weather-agent'); const response = await agent.generate('Weather in SF'); console.log(response.text);`

   You can now launch [Studio](https://mastra.ai/docs/studio/overview) and test your agent.

   **npm**:

   ```bash
   npm run dev
   ```

   **pnpm**:

   ```bash
   pnpm run dev
   ```

   **Yarn**:

   ```bash
   yarn dev
   ```

   **Bun**:

   ```bash
   bun run dev
   ```

   **For AI agents:** To validate your work, run a build and do a typecheck with `tsc --noEmit`.

## Next steps

- [Review the project structure](https://mastra.ai/reference/project-structure): Understand how `src/mastra/` files map to agents, tools, workflows, storage, and configuration.
- [Test your agent in Studio](https://mastra.ai/docs/studio/overview): Open the local Studio UI and run the weather agent.
- [Use tools with agents](https://mastra.ai/docs/agents/using-tools): Replace the example weather tool with a real tool that calls an API or service.
- [Add memory](https://mastra.ai/docs/memory/overview): Persist conversation history and user-specific context.
- [Configure storage](https://mastra.ai/docs/storage/overview): Add a persistent storage adapter for memory, workflows, observability, and other runtime state.
- [Build and deploy](https://mastra.ai/docs/deployment/overview): Build the Mastra server and deploy it to a hosting platform.