Neon
Deploy your Mastra server as a Neon Function (a long-running Node.js process) on your Neon branch. The function gets a public HTTPS URL and DATABASE_URL is injected from the branch's Postgres database.
Neon Functions are a fetch handler. This guide uses the Hono server adapter rather than mastra build / mastra start. If you're using a web framework, deploy the way you normally would for that framework.
Neon Functions are in beta and available only in AWS US East (Ohio) (aws-us-east-2). You'll need to create your project in that region.
Before you beginDirect link to Before you begin
You'll need:
- A Mastra application
- A Neon account
- A Neon project in
aws-us-east-2 - Node.js
v22.13.0or later
Neon Functions can evict an idle isolate, so in-memory and local-file storage is lost. Use PostgresStore with Neon instead of LibSQLStore with a file URL. For workspace files, use Neon Object Storage instead of LocalFilesystem.
InstallationDirect link to Installation
Install the Neon CLI:
- npm
- pnpm
- Yarn
- Bun
npm install -g neon
pnpm add -g neon
yarn global add neon
bun add --global neon
Add the Hono adapter, Hono, and @neon/config:
- npm
- pnpm
- Yarn
- Bun
npm install @mastra/hono@latest hono @neon/config
pnpm add @mastra/hono@latest hono @neon/config
yarn add @mastra/hono@latest hono @neon/config
bun add @mastra/hono@latest hono @neon/config
Configure neon.tsDirect link to configure-neonts
At the root of your project, create a file named neon.ts. neon deploy and neon dev read this file:
import { defineConfig } from '@neon/config/v1'
export default defineConfig({
preview: {
aiGateway: true,
functions: {
mastra: {
name: 'Mastra server',
source: './src/index.ts',
},
},
},
})
The object key (mastra) is the function slug. It can't be renamed after the first deploy.
aiGateway: true provisions the Neon AI Gateway on the branch. neon deploy injects NEON_AI_GATEWAY_BASE_URL and NEON_AI_GATEWAY_TOKEN. Mastra reads those variables for neon/ model ids.
For a provider API key instead of the gateway, declare it under the function's env field and use that provider's model id, not a neon/ id. Values are read from process.env when neon deploy runs:
import { defineConfig } from '@neon/config/v1'
export default defineConfig({
preview: {
functions: {
mastra: {
name: 'Mastra server',
source: './src/index.ts',
env: {
OPENAI_API_KEY: process.env.OPENAI_API_KEY!,
},
},
},
},
})
neon deploy --env .env
--env loads the file for config evaluation. Only keys listed in env are deployed. See Neon Functions environment variables.
Export a Hono fetch handlerDirect link to Export a Hono fetch handler
Wire the Hono adapter and export the app. Neon Functions invoke the default export's fetch method.
import { Hono } from 'hono'
import { HonoBindings, HonoVariables, MastraServer } from '@mastra/hono'
import { mastra } from './mastra'
const app = new Hono<{ Bindings: HonoBindings; Variables: HonoVariables }>()
const server = new MastraServer({ app, mastra })
await server.init()
export default app
Register agents on the mastra instance in src/mastra/index.ts.
import { Mastra } from '@mastra/core/mastra'
import { Agent } from '@mastra/core/agent'
const assistant = new Agent({
id: 'assistant',
name: 'Assistant',
instructions: 'You are a helpful assistant',
model: 'neon/claude-fable-5',
})
export const mastra = new Mastra({
agents: { assistant },
})
See the Neon AI Gateway for the model list.
DeployDirect link to Deploy
From the project directory, link an existing Neon project (or create one):
neon linkneon linkwrites project context to.neonand pulls the current branch's environment variables.Deploy the function:
neon deployThe CLI bundles the handler with esbuild, uploads it, and waits until the deployment status is
completed. If you declared functionenvvalues, pass--env <file>soneon.tscan read them.Get the public URL:
neon functions get mastraThe
invocation_urllooks likehttps://<branch-id>-mastra.compute.<cell>.us-east-2.aws.neon.tech/.Verify the deployment at
https://<branch-id>-mastra.compute.<cell>.us-east-2.aws.neon.tech/api/agents, which should return a JSON list of your agents.Since the Mastra server prefixes every API endpoint with
/api, add it to your URLs when making requests.DATABASE_URLis injected from the branch. Gateway credentials are injected whenaiGateway: trueis set inneon.ts.You can now call your Mastra endpoints over HTTP.
warningSet up authentication before exposing your endpoints publicly. The function URL is public. See Neon Functions authentication.
Local developmentDirect link to Local development
neon dev serves every function declared in neon.ts with hot reload, and injects the linked branch's environment variables:
neon dev
The Mastra server is at http://localhost:8787/api/agents.