provider/model string and generates its provider registry from models.dev, so every provider listed there works in Mastra without installing a provider package. ZeroGPU is listed on models.dev, which means model: 'zerogpu/deepseek-v4.1-flash' and a ZEROGPU_API_KEY are all it takes to run a Mastra agent on ZeroGPU.
ZeroGPU is a compute-efficient inference provider for apps and agents. We run purpose-built small and nano language models across an edge network for the high-volume tasks you run constantly - classification, extraction, moderation, routing, summarization - at ~10x lower latency and 50%+ lower cost than frontier-model workflows. Auto-scaling, with zero GPU infrastructure to manage. Plug in and you’re live.
Overview
This guide covers building Mastra agents on ZeroGPU, for TypeScript developers who want a low-cost, low-latency model provider behind their agents and workflows. You’ll set your key, point an agent at a ZeroGPU model string, and make your first call, then work through every surface Mastra exposes for a provider: the model router string, the OpenAI-compatible config object, unlisted ZeroGPU models,generate() and stream(), tools, memory, structured output, model settings, provider options for reasoning, fallbacks, dynamic model selection, workflows, and Mastra Studio. By the end you’ll have tool-calling agents running on ZeroGPU for well under a cent per answer.
Cookbook
For a runnable, real-world example, see Build a Trail Gear Agent with Mastra and ZeroGPU. It builds a gear assistant for an outdoor store with two tools, a live weather forecast and the shop’s catalog, runs it on DeepSeek V4.1 Flash in Mastra Studio, and then switches to GPT-5.6 Luna mid-conversation. Both answers together cost well under a cent. Check it out to see the model router, tools, memory, and Studio working end to end.For more worked examples, browse the cookbook index for
end-to-end walkthroughs of classification, extraction, and PII workflows on
ZeroGPU’s small models.
Video walkthrough
Quickstart
Prerequisites
- A ZeroGPU API key (starts with
zgpu-api-). - Node.js 22.13 or later.
@mastra/core1.85.0 or later, the first release whose provider registry includes ZeroGPU.- A chat model from the model catalog that models.dev lists. This guide uses
deepseek-v4.1-flash, which called every tool reliably in our tests.
Get your ZeroGPU API key
- Sign in to the ZeroGPU dashboard.
- Open API Keys and click Create key.
- Copy the key (starts with
zgpu-api-) and export it asZEROGPU_API_KEY, the variable models.dev lists for ZeroGPU. Mastra reads it automatically for everyzerogpu/*model.
.env file at your project root instead. mastra dev loads .env.development, .env.local, and .env for you.
.env
Install Mastra
Add Mastra to an existing TypeScript project.@mastra/core holds agents, tools, workflows, and the model router, and the mastra CLI runs Mastra Studio:
npm create mastra@latest scaffolds a new project. Either way, there’s no ZeroGPU package to install.
Your first request
Create an agent with a ZeroGPU model string and call it once:hello.ts
zerogpu in its registry, read your key from ZEROGPU_API_KEY, and sent an OpenAI-compatible POST /chat/completions request to https://api.zerogpu.ai/v1, the endpoint models.dev lists for ZeroGPU.
Usage
Every section below follows the same shape: what the surface does, what it calls on ZeroGPU, its parameters, a runnable example, and what you get back.How Mastra finds ZeroGPU
Mastra’s model router ships a provider registry generated from the models.dev catalog. ZeroGPU’s entry gives the router everything it needs, so there’s no provider to register:
These nine ZeroGPU models are in the registry. Prices are USD per 1M tokens, and the reasoning controls are explained in Provider options and reasoning.
All nine support tool calling and structured output. For cache prices, input types, and the full catalog metadata, see the Models.dev integration guide. In development, Mastra refreshes the registry from models.dev every hour; in production it uses the registry bundled with your installed
@mastra/core unless you set MASTRA_AUTO_REFRESH_PROVIDERS=true. ZeroGPU models that models.dev doesn’t list yet can be added by hand; see Unlisted ZeroGPU models.
Model router string
The simplest way to use ZeroGPU: passzerogpu/<model-id> as an agent’s model. Mastra resolves the provider, the endpoint, and the key for you, and the string is typed, so your editor autocompletes the nine ZeroGPU model IDs.
TypeScript
gpt-5.4-nano. Change the string to move the agent to any other ZeroGPU model; nothing else changes.
OpenAI-compatible config object
Use an object instead of a string when one agent needs its own key, extra headers, or a different endpoint. Mastra still treats it as a ZeroGPU model.TypeScript
ZEROGPU_API_KEY. The x-project-id header is optional; leave it out unless you track usage per project.
Unlisted ZeroGPU models
ZeroGPU serves more chat models than models.dev lists. To use one, give Mastra the endpoint yourself with theproviderId and modelId form. Model IDs are sent exactly as written, and they’re case-sensitive.
TypeScript
LFM2.5-1.2B-Instruct at ZeroGPU’s rates. Give the Llama 3.2 and LFM2.5 models agents without tools: they’re built for fast chat and summarization and reject tool definitions. Prices are from the model catalog in November 2026. When models.dev adds one of these models, switch back to the plain zerogpu/<model-id> string.
agent.generate()
Runs the agent to completion and returns the final answer. When the agent has tools, Mastra loops: each step is one POST /chat/completions call to ZeroGPU, tool calls run locally, and their results go back to the model until it answers.
TypeScript
agent.stream()
Same options as generate(), but returns as soon as ZeroGPU starts responding, so you can show text as it arrives.
TypeScript
Tools
Tools let the model fetch data or take actions. Every ZeroGPU model in the registry supports tool calling, so Mastra sends your tool schemas with each request and runs whichever tool the model picks.src/mastra/tools/search-products.ts
TypeScript
inputSchema, runs execute, and sends the result back to ZeroGPU for the next step. In our tests DeepSeek V4.1 Flash called both of the cookbook’s tools on every run. Keep descriptions specific and say in the instructions when each tool should be used.
Memory
Memory keeps a conversation’s history so follow-ups like “Keep it under $250” work. AddMemory from @mastra/memory to the agent and storage to your Mastra instance, then pass a thread and a resource with each call.
src/mastra/index.ts
TypeScript
url: ':memory:' for throwaway demos (history is lost when the process stops) and a file or hosted database for anything you want to keep.
Structured output
Returns a typed object instead of free text. Mastra’s ZeroGPU client sends your schema as a JSON-schemaresponse_format, and every registry model supports it.
TypeScript
result.object is typed from the schema. Small models such as gpt-5.4-nano handle extraction like this well, at a fraction of a chat model’s cost.
Model settings and defaults
Sampling settings for a call, set per call inmodelSettings or for every call in the agent’s defaultOptions.
TypeScript
generate() or stream() override them. topK isn’t part of the OpenAI-compatible API, so Mastra drops it with a warning.
Provider options and reasoning
Passes ZeroGPU request fields straight through. Mastra names its ZeroGPU clientzerogpu, so fields under providerOptions.zerogpu are merged into the request body. reasoningEffort is the one renamed field: it’s sent as reasoning_effort.
TypeScript
providerOptions: { zerogpu: { reasoningEffort: 'high' } }. For the Qwen models, toggle thinking with providerOptions: { zerogpu: { chat_template_kwargs: { enable_thinking: true } } }.
Response: the run reasons before answering and the reasoning tokens are billed as output. ZeroGPU doesn’t return reasoning text on this API, so result.reasoningText stays empty and Studio shows no thinking blocks.
Model fallbacks
Pass an array of models and Mastra moves to the next one when a model keeps failing. Because every entry can be a ZeroGPU model, one key covers the whole chain.TypeScript
Dynamic model selection
model can be a function that picks a model per request from the request context, for example by customer tier or task size.
TypeScript
Workflows
Workflows chain steps with typed inputs and outputs.createStep(agent) turns an agent into a step that takes { prompt } and returns { text }, so a ZeroGPU agent drops into any workflow.
TypeScript
result.result.text holds its answer. Register the workflow in new Mastra({ workflows: { gearList } }) to run it from Studio too.
Mastra Studio (mastra dev)
mastra dev starts a local server for your Mastra instance and opens Mastra Studio, where you chat with agents, watch tool calls, and switch models without editing code.
package.json
Patterns and recipes
Cheap triage in front of a capable agent. Put a small model on the decision and a stronger one on the answer. Agpt-5.4-nano agent with structured output classifies the request, and only gear questions reach the tool-using agent on deepseek-v4.1-flash:
TypeScript
providerOptions: { zerogpu: { thinking: { type: 'enabled' } } } only on requests that need planning, as in Provider options and reasoning. You pay for reasoning tokens only where they help.
A fallback chain on one key. List two or three ZeroGPU models in a fallback array. They share ZEROGPU_API_KEY and the same tool definitions, so a failover changes nothing for your tools or your billing setup.
Price a run before you scale it. Multiply result.totalUsage by the per-1M prices in the model table. A tool-calling turn that sends about 6,000 input tokens and gets 200 back on DeepSeek V4.1 Flash costs about 6,000 x $0.30/1M + 200 x $1.20/1M = $0.0020, which is why the cookbook’s two answers together cost well under a cent.
At a glance
Troubleshooting
zerogpu/... isn’t accepted as a model, or TypeScript rejects the string. Your @mastra/core predates ZeroGPU’s models.dev listing. Run npm install @mastra/core@latest to get 1.85.0 or later, then restart mastra dev.
The agent replies with an error about a missing API key. The process running Mastra can’t see ZEROGPU_API_KEY. Export it in the same terminal before npm run dev, or put it in .env at the project root, then restart. Run [ -n "$ZEROGPU_API_KEY" ] && echo set to check without printing the key.
401 or 403 invalid_api_key on the first message. The key is wrong, revoked, or picked up a stray space when pasted. Create a fresh key in the dashboard and update the variable or .env.
Studio’s model picker shows other providers as not connected. That’s expected. Studio lists every provider in Mastra’s registry and marks only the ones whose key variable is set. With just ZEROGPU_API_KEY set, ZeroGPU is the only connected provider.
npm run dev says “Another development server instance is already running”. An earlier mastra dev is still running for this folder. Stop it with Ctrl + C in its terminal; if there isn’t one, delete .mastra/dev.lock and run npm run dev again.
Chats disappear when you restart mastra dev. Your storage uses url: ':memory:', which keeps threads only while the process runs. Switch LibSQLStore to url: 'file:./mastra.db' to keep them.
The agent answers without calling its tools, or recommends products the tool didn’t return. Say in the instructions which tool to call and when, and to recommend only what the tools return. Model choice matters too: in our tests DeepSeek V4.1 Flash called both tools on every run. If the agent stops right after a tool call with no answer, raise maxSteps.
model not found for a model that isn’t in the registry. The router only knows the nine listed models. For others, use the providerId and modelId form with url, and send the exact, case-sensitive ID, such as LFM2.5-1.2B-Instruct.
An LFM2.5 or Llama 3.2 agent fails as soon as it has tools. These models don’t accept tool definitions. Give them agents without tools, and keep tool-calling agents on a registry model.
Production doesn’t see a model that development does. Development refreshes the registry from models.dev every hour, while production uses the registry bundled with your installed @mastra/core. Upgrade @mastra/core, or set MASTRA_AUTO_REFRESH_PROVIDERS=true in production.
No thinking blocks appear with reasoning turned on. ZeroGPU doesn’t return reasoning text on the chat completions API, so there’s nothing for Mastra or Studio to show. The model still reasons, and the reasoning tokens are billed as output.
Conclusion
Mastra reads ZeroGPU straight from models.dev, so moving an agent onto ZeroGPU is one model string and one environment variable, with no provider package. Tools, memory, structured output, fallbacks, and Studio all work the same way they do with any other provider, and with ZeroGPU’s low-cost models a tool-calling answer costs a fraction of a cent.Model Catalog
Browse every model available on ZeroGPU and pick the best fit.
API Reference
Explore the full OpenAI-compatible API surface.
Cookbook
Build a trail gear agent with Mastra on ZeroGPU.
Join Discord
Ask questions and share what you’re building.

