Skip to main content

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 begin
Direct link to Before you begin

You'll need:

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.

Installation
Direct link to Installation

Install the Neon CLI:

npm install -g neon

Add the Hono adapter, Hono, and @neon/config:

npm install @mastra/hono@latest hono @neon/config

Configure neon.ts
Direct link to configure-neonts

At the root of your project, create a file named neon.ts. neon deploy and neon dev read this file:

neon.ts
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:

neon.ts
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 handler
Direct link to Export a Hono fetch handler

Wire the Hono adapter and export the app. Neon Functions invoke the default export's fetch method.

src/index.ts
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.

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.

Deploy
Direct link to Deploy

  1. From the project directory, link an existing Neon project (or create one):

    neon link

    neon link writes project context to .neon and pulls the current branch's environment variables.

  2. Deploy the function:

    neon deploy

    The CLI bundles the handler with esbuild, uploads it, and waits until the deployment status is completed. If you declared function env values, pass --env <file> so neon.ts can read them.

  3. Get the public URL:

    neon functions get mastra

    The invocation_url looks like https://<branch-id>-mastra.compute.<cell>.us-east-2.aws.neon.tech/.

  4. 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_URL is injected from the branch. Gateway credentials are injected when aiGateway: true is set in neon.ts.

  5. You can now call your Mastra endpoints over HTTP.

    warning

    Set up authentication before exposing your endpoints publicly. The function URL is public. See Neon Functions authentication.

Local development
Direct 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.