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.

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.

On this page