Manual Install

Trust: ★★★☆☆ (0.90) · 0 validations · developer_reference

Published: 2026-05-10 · Source: crawler_authoritative

Tình huống

Step-by-step guide for manually setting up a standalone Mastra server without using the automatic CLI tools, for developers who want full control over the project structure.

Insight

The manual install process involves 7 steps: (1) Create project directory and initialize with npm/pnpm/yarn/bun, (2) Install dependencies including typescript, @types/node, mastra@latest, @mastra/core@latest, and zod@^4, (3) Configure tsconfig.json with ES2022 target, ES2022 module, bundler moduleResolution, strict mode, and noEmit set to true, (4) Create .env file with API key (default uses GOOGLE_GENERATIVE_AI_API_KEY but supports any model provider like OpenAI, Anthropic), (5) Create a tool file using createTool from @mastra/core/tools with inputSchema and outputSchema using zod, (6) Create an agent file using Agent class from @mastra/core/agent with id, name, instructions, model (google/gemini-2.5-pro), and tools, (7) Create Mastra entry point importing Mastra class and registering agents. Important caveats: Mastra requires modern module and moduleResolution settings — CommonJS or node settings will cause resolution errors. The guide uses a simplified weather tool example and references the full example in the ‘Giving an Agent a Tool’ documentation.

Hành động

Create a new directory (mkdir my-first-agent && cd my-first-agent). Initialize package.json with npm init/pnpm init/yarn init/bun init. Install dependencies: npm install -D typescript @types/node mastra@latest && npm install @mastra/core@latest zod@^4 (or equivalent for pnpm/yarn/bun). Create tsconfig.json with ES2022 compiler options including moduleResolution: ‘bundler’ and strict: true. Create .env file with GOOGLE_GENERATIVE_AI_API_KEY=. Create src/mastra/tools/weather-tool.ts using createTool with zod schemas for input/output. Create src/mastra/agents/weather-agent.ts using new Agent() with model ‘google/gemini-2.5-pro’ and tools configuration. Create src/mastra/index.ts exporting new Mastra({ agents: { weatherAgent } }). Launch with npm run dev / pnpm run dev / yarn dev / bun run dev to start Studio.

Kết quả

Launch Mastra Studio in the browser to test the configured weather agent with its tool.

Điều kiện áp dụng

Supports npm, pnpm, yarn, and bun package managers. Can use any supported model provider (Google Gemini, OpenAI, Anthropic). Note: Mastra requires ES2022 module and bundler moduleResolution settings — CommonJS or node settings will cause resolution errors.

---

Nội dung gốc (Original)

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 quickstart guide, 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

   Generate a new package.json file:

   npm:

   npm init

   pnpm:

   pnpm init

   Yarn:

   yarn init

   Bun:

   bun init

   Install the following dependencies:

   npm:

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

   pnpm:

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

   Yarn:

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

   Bun:

   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:

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

2. Create a tsconfig.json file:

   touch tsconfig.json

   Add the following configuration:

   {
     "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:

   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:

   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:

   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:

   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:

   npm run dev

   pnpm:

   pnpm run dev

   Yarn:

   yarn dev

   Bun:

   bun run dev

Liên kết

• Nền tảng: Dev Framework · Mastra
• Nguồn: https://mastra.ai/docs/getting-started/manual-install

Xem thêm:

• Mastra Project Structure
• Studio Deployment
• Laminar exporter
• BrowserViewer - CLI-Based Browser Automation for Agents