Skip to main content

Manual Install

info

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

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

    Initialize a TypeScript project and install the following dependencies:

    npm init -y
    npm install -D typescript @types/node mastra@beta
    npm install @mastra/core@beta zod@^4

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

    package.json
    {
      "scripts": {
        "test": "echo \"Error: no test specified\" && exit 1",
        "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_GENERATIVE_AI_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 () => {
        return {
          output: "The weather 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";

    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";

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

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

    npm run dev