Join our Newsletter — 33% off our NHI Course
Home› Guides› What Is Mastra? TypeScript Agent Framework Explained: Features,…
Guide AI Platforms

What Is Mastra? TypeScript Agent Framework Explained: Features, Versions, Licence and Pricing

PDF for newsletter subscribers · free to read online

← All guides
By NHI Mgmt Group, edited by Lalit Choda Updated 15 November 2026 13 min read
On this page

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/core 1.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.auth before 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.

ComponentPackage or commandWhat it does
Core framework@mastra/coreAgents, tools, workflows, processors, model router
Memory@mastra/memoryMessage history, Observational Memory, working memory, semantic recall
Servermastra build (Hono-based server)Exposes agents, workflows and tools as HTTP endpoints, with an OpenAPI spec
Studiomastra devLocal UI for testing agents, running workflows and inspecting traces
ClientMastra Client SDKType-safe calls to agents, workflows and tools from browser or server
Platformmastra deployHosted Observability, Studio and Server products

Key facts at a glance

As of 15 November 2026, from the repository, changelog and docs.

FieldValue
DeveloperKepler Software, Inc. (Mastra)
LanguageTypeScript
LicenceApache 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
RuntimesNode.js 22.13.0 or later, Bun, Deno, Cloudflare
Quick startnpm create mastra@latest
Model accessModel router with 40+ providers, using provider/model-name strings
Default local port4111 (or the PORT environment variable)
ProtocolsBuilt-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:

PlanPrice (USD)Memory / vCPU includedObservability eventsTrace retentionProjectsCompliance and access features
Free$0100 GB-hours / 40 vCPU-hours100K15 daysServerless onlyNone listed
Starter$25360 GB-hours / 100 vCPU-hours250K60 days1 SmallUsage alerts
Team$2503.6K GB-hours / 400 vCPU-hours10M180 days1 Small, 2 MediumSOC 2 report
EnterpriseCustomCustomCustomCustomCustomRBAC, 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 with mastra.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 agents property, choosing by each subagent's description.
  • Code mode (added in core 1.38.0): createCodeMode() lets the model write one TypeScript function (tool id execute_typescript by 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 typeWhat it doesDefault
Message historyLast N messages for a resource (user) and thread (conversation)On
Observational MemoryBackground agents compress older messages into observations; optional recall toolOff; docs mark it "Recommended"; recall off until retrieval: true
Working memoryPersistent structured facts such as names, preferences and goalsOff
Semantic recallVector search over earlier messagesOff
Multi-user threadsOne thread shared by several usersOff

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

NeedPrimitive the docs point toWhy
Open-ended task, steps unknownAgentThe agent decides tools, loops and when to stop
Known steps in a set orderWorkflowExplicit control of data flow and which primitive runs at each stage
Several specialisms in one taskSubagents under a supervisorThe parent delegates, passes context and synthesises results
Many tool calls to answer one queryCode modeFewer round trips, smaller context, arithmetic run as code
Sensitive or costly toolApproval or suspensionA person confirms before or during execution
Long conversationsObservational MemoryKeeps the context window small while retaining earlier information

Supported IDEs and platforms

Deployment optionHow it works (per the docs)
Mastra servermastra build output on a VM, container or PaaS; suits long-running processes and WebSockets
Web frameworkDeploy alongside a Next.js or Astro app
Cloud deployersOptional built-in deployers for Cloudflare, Netlify and Vercel
SandboxEphemeral workspace sandbox with a live URL, for previews or per-user instances
Workflow runnersBuilt-in engine by default; Inngest supported; @mastra/temporal described as experimental
WorkersWorkflow orchestration, cron and background tools in separate processes
Mastra platformmastra 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.auth supports Simple Auth, JWT and providers including Auth0, Better Auth, Clerk, Firebase, Google, Neon, Okta, Supabase and WorkOS, plus CompositeAuth and custom providers. By default it protects /api/* and treats /api and /api/auth/* as public. If you change server.apiPrefix, update the protected and public patterns too.
  • Studio access: studio.auth can give Studio its own provider.
  • RBAC and FGA: server.rbac, studio.rbac and server.fga add 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 older MASTRA_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)VersionMilestone
17 February 2025@mastra/core 0.2.0Early 0.x release
21 May 20250.10.00.x line
20 January 20261.0.0First stable major
25 February 20261.8.0Subagents (supervisor pattern)
3 April 20261.22.0Channels for Slack, Discord and Telegram
2 June 20261.38.0Code mode
12 November 20261.83.0Latest 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; LocalSandbox runs model-written code on the host. See the AI Agent Sandboxing and Code Execution Guide.
  • Use requireApproval on destructive or costly tools. See the Human-in-the-Loop for AI Agents Guide.
  • Set guardrails to strict where 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/core and @mastra/memory in 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 (and studio.auth if 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 LocalSandbox outside 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

Related NHI Mgmt Group resources: Mastra Agent Framework Security Guide · Securing Agent Frameworks Guide · Agent Frameworks vs Workflow Orchestration · AI Agent Memory Security Guide

PDF for subscribers

Take this guide with you

Every section, table and checklist in one PDF, with links to the sources and related guides. Subscribe to our weekly NHI & AI Identity Journal and we’ll email you a download link.

Free weekly newsletter

Subscribe to the NHI & AI Identity Journal

The latest on NHI and Agentic AI security – articles, research, breaches, news and events every week.

Bonus 33% off our NHI Course when you subscribe.

NHIMG Editorial Note
Researched and written by the NHI Mgmt Group editorial team using AI tools, under the editorial direction of Lalit Choda. Facts are drawn from the sources listed on this page and checked by our automated quality process. Last updated 15 November 2026. Spotted an error? Use our contact page.
NHI Mgmt Group, the independent authority on Non-Human Identity, IAM and Agentic AI security. nhimg.org

PDF Downloads for Newsletter Subscribers

Get the guide

Enter your details and we’ll email you a download link.

The full guide is free to read online. The PDF is a thank you for subscribing.

Fill in all fields marked * and tick the PDF box to continue.