Skip to main content

Manual install

Use this guide to manually build a standalone Mastra server step by step. In most cases, it's quicker to follow the quickstart guide, which achieves the same result using the mastra create command. For existing projects, you can also use mastra init.

Instructions
Direct link to 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:

    mkdir my-first-agent && cd my-first-agent

    Generate a new package.json file:

    npm init

    Install the following dependencies:

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

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

    package.json
    {
      "scripts": {
        "dev": "mastra dev",
        "build": "mastra build"
      }
    }

  2. 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/**/*"]
    }
    info

    Mastra requires modern module and moduleResolution settings. Using CommonJS or node will cause resolution errors.

  3. Create an .env file:

    touch .env

    Add your API key:

    .env
    GOOGLE_API_KEY=<your-api-key>
    note

    This guide uses Google Gemini, but you can use any supported model provider, including OpenAI, Anthropic, and more.

  4. 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 ({ 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.

  5. 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 { 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:

    touch src/mastra/index.ts

    Add the following code:

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

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

  7. You can now launch Studio and test your agent.

    npm run dev

Next steps
Direct link to Next steps

On this page