Mastra is an open source TypeScript framework from Kepler Software, Inc. for building AI agents, graph-based workflows and the servers that expose them, with a commercial platform for hosting, Studio and observability alongside it. Teams evaluating it usually want to know what the framework does on its own, which parts need an enterprise licence, what the hosted platform costs and how quickly the 1.x line is moving. This page answers those questions for developers, architects and the people who approve frameworks for a team. It covers agents, workflows, memory, guardrails, deployment targets, authentication defaults, licensing and release history. Every fact comes from Mastra's own documentation, repository, changelog and pricing page. Last checked: 2026-11-15.
This is an independent guide from NHI Mgmt Group, based on Mastra's public documentation as of November 2026. It is not sponsored or reviewed by Mastra. Product features change, so confirm settings against Mastra's current documentation.
Key takeaways
- Agents for open tasks, workflows for known steps. Mastra's docs say to use agents when the steps are not known in advance and workflows when the order is defined upfront; the two compose in both directions.
- Fast-moving 1.x line.
@mastra/core1.0.0 was tagged on 20 January 2026 and 1.83.0 on 12 November 2026, so pin versions and read the changelog before upgrading. - Apache 2.0, with an enterprise carve-out. Code outside
ee/directories is Apache 2.0; RBAC, fine-grained authorisation, Agent Builder and third-party Studio sign-in need an Enterprise Edition licence in production. - Authentication is opt-in. The docs state that with no auth configured, all routes and Studio are publicly accessible, so configure
server.authbefore any non-local deployment. - Platform plans start at $0. Mastra platform has Free, Starter ($25), Team ($250) and custom Enterprise plans per workspace per month, plus usage-based compute and observability charges.
What is Mastra?
The repository README describes Mastra as "a framework for building AI-powered applications and agents with a modern TypeScript stack". It integrates with React, Next.js and Node, or runs as a standalone server. The framework's building blocks are agents, tools and workflows, registered on a central Mastra instance so they share storage, logging and observability.
Agents "use LLMs and tools to solve open-ended tasks": they decide which tools to call, how many times to loop and when to stop, continuing until the model returns a final answer or an optional stop condition is met. Workflows are for "tasks that are clearly defined upfront and involve multiple steps with a specific execution order", built from typed steps with explicit control flow. A workflow step can call an agent, and an agent can run a workflow.
The copyright line in the licence names Kepler Software, Inc., and the README carries a Y Combinator W25 badge. Pull requests are limited to collaborators; outside contributors are asked to file issues instead.
| Component | Package or command | What it does |
|---|---|---|
| Core framework | @mastra/core | Agents, tools, workflows, processors, model router |
| Memory | @mastra/memory | Message history, Observational Memory, working memory, semantic recall |
| Server | mastra build (Hono-based server) | Exposes agents, workflows and tools as HTTP endpoints, with an OpenAPI spec |
| Studio | mastra dev | Local UI for testing agents, running workflows and inspecting traces |
| Client | Mastra Client SDK | Type-safe calls to agents, workflows and tools from browser or server |
| Platform | mastra deploy | Hosted Observability, Studio and Server products |
Key facts at a glance
As of 15 November 2026, from the repository, changelog and docs.
| Field | Value |
|---|---|
| Developer | Kepler Software, Inc. (Mastra) |
| Language | TypeScript |
| Licence | Apache 2.0, except ee/ directories under the Mastra Enterprise License |
| Latest stable core | @mastra/core 1.83.0 (tagged 12 November 2026); 1.84.0 in alpha on main |
| Runtimes | Node.js 22.13.0 or later, Bun, Deno, Cloudflare |
| Quick start | npm create mastra@latest |
| Model access | Model router with 40+ providers, using provider/model-name strings |
| Default local port | 4111 (or the PORT environment variable) |
| Protocols | Built-in MCP server at /api/mcp; A2A agent cards and task streams |
| Security contact | [email protected] |
Plans and pricing
The framework is free to use under Apache 2.0; you pay your model providers directly. Mastra charges for its hosted platform and for Enterprise Edition licences. Platform plans are priced per workspace per month:
| Plan | Price (USD) | Memory / vCPU included | Observability events | Trace retention | Projects | Compliance and access features |
|---|---|---|---|---|---|---|
| Free | $0 | 100 GB-hours / 40 vCPU-hours | 100K | 15 days | Serverless only | None listed |
| Starter | $25 | 360 GB-hours / 100 vCPU-hours | 250K | 60 days | 1 Small | Usage alerts |
| Team | $250 | 3.6K GB-hours / 400 vCPU-hours | 10M | 180 days | 1 Small, 2 Medium | SOC 2 report |
| Enterprise | Custom | Custom | Custom | Custom | Custom | RBAC, SSO, audit logs |
As of 15 November 2026, from mastra.ai/pricing. Overage is $0.25 per GB-hour of memory, $0.25 per vCPU-hour, $0.50 per connection, $0.10 per GB of egress and $10 per 100K observability events; deploys are unlimited on every plan. Always-on project sizes cost $25 (Small: 2 GB, 1 vCPU), $100 (Medium: 8 GB, 4 vCPU) and $200 (Large: 16 GB, 8 vCPU) per month, and Serverless (1 GB, 0.5 vCPU) scales to zero. Enterprise Edition licence pricing is through sales.
Models available
Agents name a model as a provider/model-name string resolved by Mastra's model router, which the README says connects to "40+ providers through one standard interface", including OpenAI, Anthropic and Gemini. Each provider reads its own API key from the environment (for example OPENAI_API_KEY). The create mastra starter offers openai, anthropic, google and xai as setup choices. Instructions and models can be swapped per request through request context, which the docs call dynamic configuration.
Features and modes
Agents
- Calling:
.generate()returns the full result (text, tool calls, tool results, steps and token usage);.stream()streams tokens. Retrieve agents withmastra.getAgentById()so they get shared services. - Tools: functions with schemas, other agents registered as tools, and MCP tools.
- Structured output: typed objects instead of plain text.
- Subagents (added in core 1.8.0): a parent "supervisor" agent delegates to agents listed in its
agentsproperty, choosing by each subagent'sdescription. - Code mode (added in core 1.38.0):
createCodeMode()lets the model write one TypeScript function (tool idexecute_typescriptby default) that orchestrates several tools inside a sandbox, while the real tools keep running on the host. - Channels (added in core 1.22.0): connect agents to Slack, Discord or Telegram.
Workflows
Steps are created with createStep() and composed with createWorkflow(), each with inputSchema and outputSchema in any Standard JSON Schema library (Zod, Valibot, ArkType). Control flow uses .then(), .branch(), .parallel() and loops such as dountil and dowhile. Workflows support shared state, nested workflows, cloneWorkflow(), suspend and resume, scheduled runs and "time travel" replay of individual steps in Studio.
Memory
| Memory type | What it does | Default |
|---|---|---|
| Message history | Last N messages for a resource (user) and thread (conversation) | On |
| Observational Memory | Background agents compress older messages into observations; optional recall tool | Off; docs mark it "Recommended"; recall off until retrieval: true |
| Working memory | Persistent structured facts such as names, preferences and goals | Off |
| Semantic recall | Vector search over earlier messages | Off |
| Multi-user threads | One thread shared by several users | Off |
A thread's owner (resourceId) cannot change after creation. The docs warn that Observational Memory turns off without a warning on a storage adapter that does not support it.
Processors and guardrails
Input processors run before messages reach the model and output processors run before responses reach the user. Built-ins include UnicodeNormalizer(), PromptInjectionDetector() and LanguageDetector(). Model-backed guardrails other than ClassifierProcessor default to errorStrategy: 'warn'; set 'strict' where unchecked content must not proceed if the guardrail model fails.
Human in the loop
Mastra offers two mechanisms. Pre-execution approval pauses a tool call before its execute function runs: mark the tool requireApproval: true and handle the tool-call-approval chunk in the stream to approve or decline. Runtime suspension lets a tool start, discover it needs confirmation or extra data, and suspend until the user replies. The docs suggest approval for destructive or irreversible actions (deleting records, sending emails, processing payments), cost-heavy calls and conditional confirmation. Both rely on snapshots, so a storage provider must be configured; workflows use the same suspend and resume model and can pause indefinitely.
Observability and evals
The README lists built-in evals and observability as production essentials. Studio shows tool calls, responses and workflow runs during development, with live step status, inputs, outputs, state and logs. In production, traces can go to Mastra platform Observability, including from self-hosted applications through the MastraPlatformExporter. Platform Alerts notify Slack, email or webhooks when deploys fail or services stop, and Trace Intelligence (private beta) looks for recurring goals, outcomes and behaviours across traces.
Choosing the right primitive
| Need | Primitive the docs point to | Why |
|---|---|---|
| Open-ended task, steps unknown | Agent | The agent decides tools, loops and when to stop |
| Known steps in a set order | Workflow | Explicit control of data flow and which primitive runs at each stage |
| Several specialisms in one task | Subagents under a supervisor | The parent delegates, passes context and synthesises results |
| Many tool calls to answer one query | Code mode | Fewer round trips, smaller context, arithmetic run as code |
| Sensitive or costly tool | Approval or suspension | A person confirms before or during execution |
| Long conversations | Observational Memory | Keeps the context window small while retaining earlier information |
Supported IDEs and platforms
| Deployment option | How it works (per the docs) |
|---|---|
| Mastra server | mastra build output on a VM, container or PaaS; suits long-running processes and WebSockets |
| Web framework | Deploy alongside a Next.js or Astro app |
| Cloud deployers | Optional built-in deployers for Cloudflare, Netlify and Vercel |
| Sandbox | Ephemeral workspace sandbox with a live URL, for previews or per-user instances |
| Workflow runners | Built-in engine by default; Inngest supported; @mastra/temporal described as experimental |
| Workers | Workflow orchestration, cron and background tools in separate processes |
| Mastra platform | mastra deploy or push-to-deploy from GitHub |
The docs list further deployment guides, including Amazon Bedrock AgentCore, AWS Lambda, Azure App Services, Kubernetes and Render. For development, Studio runs locally with mastra dev, and the README describes installing Mastra skills for detected coding assistants during project creation.
Enterprise and admin controls
- Authentication:
server.authsupports Simple Auth, JWT and providers including Auth0, Better Auth, Clerk, Firebase, Google, Neon, Okta, Supabase and WorkOS, plusCompositeAuthand custom providers. By default it protects/api/*and treats/apiand/api/auth/*as public. If you changeserver.apiPrefix, update the protected and public patterns too. - Studio access:
studio.authcan give Studio its own provider. - RBAC and FGA:
server.rbac,studio.rbacandserver.fgaadd role-based and resource-level checks. When FGA is configured, protected actions without an authenticated user are denied. - Licence key: Enterprise Edition features read
MASTRA_LICENSE_KEY(or the olderMASTRA_EE_LICENSE). Without it in production, RBAC, FGA or Agent Builder stop the server from starting. - Availability: on the platform, SOC 2 reports start at Team and RBAC, SSO and audit logs are Enterprise. In the framework, the EE features listed above need a licence in production and work without one in development and testing.
Data handling and privacy
Self-hosted, Mastra keeps memory, snapshots and traces in the storage providers you configure, and sends prompts only to the model providers and tools you call. On the platform, the region is fixed when an environment is created: us (default, Portland, Oregon) or eu (Amsterdam), and the hosted database and observability data follow it. Agent-run snapshots hold only what is needed to resume and are deleted when the run finishes; conversation history lives in memory and the execution record in traces. Treat memory stores as personal data: see the AI Agent Memory Security Guide.
Release history
| Date (tag commit) | Version | Milestone |
|---|---|---|
| 17 February 2025 | @mastra/core 0.2.0 | Early 0.x release |
| 21 May 2025 | 0.10.0 | 0.x line |
| 20 January 2026 | 1.0.0 | First stable major |
| 25 February 2026 | 1.8.0 | Subagents (supervisor pattern) |
| 3 April 2026 | 1.22.0 | Channels for Slack, Discord and Telegram |
| 2 June 2026 | 1.38.0 | Code mode |
| 12 November 2026 | 1.83.0 | Latest stable at time of checking |
Dates are the commit dates of the matching @mastra/core git tags. Feature versions come from the "Added in" notes on each documentation page.
Limits and known constraints
- Node.js floor: Node.js 22.13.0 or later.
- Storage dependencies: human-in-the-loop and suspend and resume need a storage provider ("snapshot not found" otherwise), and Observational Memory needs a supporting adapter.
- Release cadence: over 80 minor core releases in the 1.x line within ten months; behaviour fixes (for example loop retry counting in 1.84.0 alpha) can change what step code observes.
- Experimental and beta pieces: the Temporal runner is experimental and Trace Intelligence is a private beta.
- Fixed regions: a platform environment's region cannot be changed after creation.
- Contribution model: pull requests are limited to collaborators.
Security guidance
These are customer-side settings under shared responsibility:
- Turn on authentication before any deployment beyond localhost, since routes and Studio are public without it, and check the protected path patterns if you change the API prefix.
- Choose the code mode boundary deliberately: pass a workspace sandbox or use the isolated V8 transport;
LocalSandboxruns model-written code on the host. See the AI Agent Sandboxing and Code Execution Guide. - Use
requireApprovalon destructive or costly tools. See the Human-in-the-Loop for AI Agents Guide. - Set guardrails to
strictwhere a failed classifier must block, and set memory scopes on the server, never from the request body. - Secure the built-in MCP server at
/api/mcp, which uses the same auth as the HTTP API. See the MCP Security Guide. - Apply vendor security updates promptly and pin package versions in lock files.
Deeper hardening is in the Mastra Agent Framework Security Guide, and is not repeated here.
Practitioner checklist
- Pin
@mastra/coreand@mastra/memoryin the lock file and review the changelog before each upgrade. - Confirm Node.js 22.13.0 or later in every build and runtime image.
- Configure
server.auth(andstudio.authif needed) before exposing port 4111 or any deployed server. - Decide whether you need RBAC, FGA or Agent Builder, and budget for an Enterprise Edition licence if so.
- Configure a storage provider before relying on approvals, suspend and resume or Observational Memory.
- Choose a sandbox for code mode and avoid
LocalSandboxoutside development. - Pick the platform region at environment creation if data residency matters.
- Send traces to an observability backend and set retention to match your data policy.
Standards and references
- Mastra: Agents overview
- Mastra: Auth
- Mastra: License
- Mastra: Repository README
- Mastra: LICENSE.md
- Mastra: @mastra/core changelog
- Mastra: Pricing
Related NHI Mgmt Group resources: Mastra Agent Framework Security Guide · Securing Agent Frameworks Guide · Agent Frameworks vs Workflow Orchestration · AI Agent Memory Security Guide