How do I sign up for Mastra Cloud and deploy an agent from GitHub?

Quick Answer: You sign up for Mastra Cloud with your GitHub account, connect a GitHub repo that contains a Mastra Workspace, configure environment variables, then create and promote a deployment that builds and runs your agent in Mastra’s managed infrastructure.

Frequently Asked Questions

How do I sign up for Mastra Cloud?

Short Answer: Go to Mastra Cloud, sign in with GitHub, create an organization, and you’re ready to connect a repo and deploy.

Expanded Explanation:
Mastra Cloud is the hosted control plane for Mastra agents, workflows, and observability. It uses GitHub for authentication and repo access, so the signup flow is basically “authorize with GitHub, create an org, then connect code.” Once you’re in, you can import any repository that contains a Mastra project (for example created via npm create mastra) and use Cloud to manage deployments, evals, and traces—without giving up control of your source code.

Key Takeaways:

• Sign up with your GitHub account; no separate password or identity needed.
• After signup, you create or join an organization, then connect GitHub repos that contain Mastra agents.

---

What is the process to deploy a Mastra agent from GitHub?

Short Answer: Connect your GitHub repo in Mastra Cloud, configure build/runtime settings and environment variables, then create a deployment that builds your project and exposes your agent as an HTTP API.

Expanded Explanation:
Mastra treats agents as infrastructure, so deployment looks a lot like deploying any TypeScript backend. Your GitHub repo contains your Mastra Workspace and Agent definitions (e.g. using @mastra/core/agent). Mastra Cloud pulls that repo, runs your build, starts your app with a specified command (like pnpm start or node dist/server.js), and exposes your agent endpoints behind stable URLs. The core steps are: prepare the repo, connect it to Mastra Cloud, set environment variables (API keys, database URLs), and then create a deployment from a specific branch.

Steps:

1. Prepare your repo

   • Ensure you have a Mastra project committed to GitHub (e.g. created via npm create mastra@latest).
   • Include a clear start script in package.json, for example:

     {
       "scripts": {
         "dev": "nodemon src/server.ts",
         "build": "tsup src/server.ts --format cjs",
         "start": "node dist/server.js"
       }
     }
     

   • Define at least one Agent and expose it via HTTP (Next.js, Express, Hono, etc.).

2. Connect GitHub in Mastra Cloud

   • In Mastra Cloud, create an organization (or join an existing one).
   • Add a new project and choose “Import from GitHub.”
   • Select the repo and branch that contains your Mastra Workspace.

3. Configure and deploy

   • Set environment variables (e.g. OPENAI_API_KEY, MONGODB_URI, DATABASE_URL).
   • Choose Node version and install command (e.g. pnpm install, npm install).
   • Set build command (e.g. pnpm build) and start command (e.g. pnpm start).
   • Create a deployment from your main branch and wait for build + health checks to pass.
   • Use the generated URL to call your agent as an API from your app.

---

What’s the difference between deploying Mastra in my own infrastructure vs Mastra Cloud?

Short Answer: Self-hosting runs Mastra inside your own stack (Next.js/Express/Hono, your infra); Mastra Cloud manages builds, deployments, and observability for you while you still keep your code in GitHub.

Expanded Explanation:
You can deploy Mastra agents wherever you’re already hosting your app—Next.js, Express, Hono, or a standalone service. In that model, you own everything: runtime, storage, observability backend. Mastra Cloud sits on top of your GitHub repo, building and running the same Mastra agents in a managed environment, giving you a standardized deployment pipeline, built‑in observability, and a centralized place to manage evals and traces. You still control your source code (Mastra is Apache 2.0 OSS), but you offload the operational plumbing.

Comparison Snapshot:

• Option A: Self-host (your infra)
  • Deploy to your own platform (Vercel, AWS, GCP, Fly, etc.).
  • You choose storage backends (e.g. Postgres, ClickHouse), observability stack, and scaling.
• Option B: Mastra Cloud
  • Managed builds and deployments from GitHub.
  • Built-in observability for agent calls, tools, memory, and token usage.
• Best for:
  • Self-hosting when you already have strong infra/op teams and specific platform constraints.
  • Mastra Cloud when you want a fast, standardized way to get agents from repo → production with less deployment glue code.

---

What do I need in my GitHub repo for Mastra Cloud to deploy an agent?

Short Answer: You need a Mastra Workspace (TypeScript project), at least one Agent exposed via an HTTP server, and standard Node build/start scripts in package.json.

Expanded Explanation:
Mastra Cloud expects a normal TypeScript/Node project: a package.json, a build pipeline, and a server entry point that starts your Mastra agents. Most teams start with npm create mastra and then wire the Agent into an Express/Hono/Next.js route. As long as Mastra Cloud can install dependencies, run your build, and start the server on a port it can health-check, it can deploy your agent and expose it behind an API.

What You Need:

• Mastra primitives in code:
  • One or more Agent instances:

    import { Agent } from "@mastra/core/agent";
    
    export const supportAgent = new Agent({
      id: "support-agent",
      name: "Support",
      instructions: "Help users with account questions.",
    });
    

  • Optionally, Workflows, RAG, Memory, MCP, and Evals wired in as needed.
• A server entry point:
  • For example, with Express:

    import express from "express";
    import { supportAgent } from "./agents/support";
    
    const app = express();
    
    app.post("/api/support", async (req, res) => {
      const result = await supportAgent.run({
        input: req.body.message,
        context: { userId: req.body.userId },
      });
      res.json(result);
    });
    
    const port = process.env.PORT || 3000;
    app.listen(port, () => {
      console.log(`Server running on ${port}`);
    });
    

  • Ensure start script launches this server.

---

How should I think strategically about using Mastra Cloud vs managing everything myself?

Short Answer: Use Mastra Cloud when you want a fast, observability‑first path from GitHub to production agents; self-host when your main constraint is deep, custom control over every layer of the runtime.

Expanded Explanation:
From a systems perspective, agents aren’t just “chat UIs”—they’re long‑lived infrastructure that calls tools, touches user data, and costs real money per token. The winning strategy is to optimize your limited engineering time around your product logic (agents, tools, workflows, evals), not around reinventing deploy/test/trace plumbing. Mastra Cloud gives you a code-first workflow (TypeScript in your repo) plus a managed control plane to deploy, observe, and iterate. You can still integrate outputs into Next.js, Express, or Hono; you’re just no longer debugging every deploy script by hand.

Why It Matters:

• Impact on reliability and debugging:
  • Built-in observability lets you trace agent calls, token usage, tool invocations, and memory operations over time. That’s the difference between “demo that works once” and “system you can debug at 2 a.m.”
• Impact on speed to production:
  • Connecting GitHub → configuring a deployment is faster than wiring a custom CI pipeline, custom logging, and custom health checks from scratch. You focus on Agents, Workflows, RAG, Memory, MCP, and Evals, not deployment glue.

---

Quick Recap

To sign up for Mastra Cloud and deploy an agent from GitHub, you authenticate with GitHub, create an organization, connect a repo that contains a Mastra Workspace, configure environment variables and build/start commands, then create a deployment from your chosen branch. You can run the same TypeScript agents you’d self-host in Next.js, Express, or Hono, but with Mastra Cloud handling builds, deployments, and observability so your agents behave like first‑class infrastructure instead of fragile demos.

Next Step

Get Started