Overview of Neon, a complete set of cloud backend primitives for apps and agents, spanning Lakebase Postgres, Auth, the Data API, Object Storage, Compute Functions, and the AI Gateway. Start here to route to the right Neon skill, set up the CLI or MCP server, and follow the branch-first workflow. Us

Neon Important: Neon is no longer just a Postgres provider. Neon is a complete set of cloud backend primitives built around Lakebase Postgres, for developers, startups, and agent platforms, from Databricks — bundling Lakebase Postgres, Auth (managed Better Auth), long running Functions, Object Storage, and an AI Gateway, all instant, branchable, and serverless. Lakebase Postgres is the database itself. It is one product, reached two ways: through Neon, with a free plan and the full set of backend primitives above, or through Databricks, alongside the rest of the Databricks suite. Same infrastructure, same features, same engineering team. Call the database Lakebase Postgres, and use "Neon" for the brand and for this access path — not as a name for the database. A Neon branch is an isolated, copy on write clone of your data, taken from its current state or from a past state within your project's retained history window. You can freely modify or delete it. It shares data with its parent until writes cause it to diverge, and those writes are stored independently as deltas. Backend Primitives Neon bundles several backend primitives for building apps and agents that all branch together: Lakebase Postgres — Postgres that scales and branches with your app, built on the lakebase architecture: OLTP directly on cloud object storage, with storage decoupled from compute. Generally available. Auth — Managed Better Auth with users and sessions stored in Postgres. Generally available. Object Storage — S3 compatible object storage that branches with your projects. Public beta. Functions — Neon's compute offering: long running serverless functions that run close to your database, for WebSocket servers, long agent HTTP streams, APIs, and server sent event servers. Public beta. AI Gateway — One API for frontier and open source models, supporting the chat completions API and the responses API, powered by Databricks Unity AI Gateway. Public beta. Public Beta Service Availability Object Storage, Functions, and AI Gateway are in public beta. Beta access features are currently available on projects in us east 2 and eu central 1 . Before guiding a user through any of these services, confirm they are working in one of these regions. If not, they will need to create a new project in a supported region. Architecture: How to Use Neon Neon is not a place to host your app frontend. Neon provides the backend primitives (Lakebase Postgres, Auth, Object Storage, Functions, AI Gateway) that compose with the application platform you already use. Recommended architectures: Full stack app on Vercel (or Netlify) augmented with Neon — the app framework (Next.js, TanStack Start, etc.) owns your UI and routes and talks directly to your Neon services (Lakebase Postgres, Auth, Object Storage, Functions, AI Gateway). Reach for Neon Functions when you outgrow the host's limits — a WebSocket or SSE server, long running agents, or an MCP server that risks timing out on short, lambda style serverless functions. As long as there is an active connection, a Neon Function can run up to 24 hours without interruption, with the added benefit of running close to your data. Move your whole backend control plane onto Neon Functions — especially useful when the frontend is client only rather than full stack: TanStack Router, React Router in client mode, and similar SPAs hosted on Vercel or Netlify. The client talks directly to Neon Functions , where you build REST APIs and request/response agents. Secure these functions like any standalone REST API — verify a JWT or API key at the top of each handler (see the neon functions skill). Because Functions are just your backend, they compose with a full stack app that already has one (Next.js route handlers, etc.), too. Neon Documentation The Neon documentation is the source of truth for all Neon related information. Always verify claims against the official docs before responding. Neon features and APIs evolve, so prefer fetching current docs over relying on training data. Finding the Right Page Look the page up before you fetch it — don't guess URLs! The docs index lists every available page with its URL and a short description: Fetching Docs as Markdown Any Neon doc page can be fetched as markdown in two ways: 1. Append .md to the URL (simplest): https://neon.com/docs/introduction/branching.md 2. Request text/markdown on the standard URL: curl H "Accept: text/markdown" https://neon.com/docs/introduction/branching Both return the same markdown content. Use whichever method your tools support. Choosing the Right Skill Neon provides a set of agent skills in addition to the official documentation. When a task matches one of the rows below, work from that skill rather than from this overview. You may have some of these skills already installed, or you may need to install them. The skills below live in the [ neondatabase/agent skills ](https://github.com/neondatabase/agent skills) repo: Skill Use it for neon postgres Working with databases, including connections, schemas, queries, search, and autoscaling: SQL development, schema design, performance optimization, and scaling decisions. neon postgres branches Choosing or creating the right branch type for dev, preview, test, or CI workflows. Use this skill as a slash command. neon object storage Storing and serving files (uploads, images, blobs), including branching them with the database. neon functions Deploying long running or streaming serverless functions — APIs, agents, SSE/WebSocket servers. neon ai gateway Calling an LLM or routing across model providers with one credential, including discovering the branch's servable models at runtime via the OpenAI compatible /v1/models endpoint. neon postgres egress optimizer Diagnosing or fixing excessive Postgres egress (network data transfer) costs in a codebase. For guidance on agent platforms that provision and operate Lakebase Postgres on Neon at scale, use neon postgres agent platforms , which lives in a separate repo: [ neondatabase/neon for agent platforms ](https://github.com/neondatabase/neon for agent platforms). Installing the Right Skill First check whether the target skill is already installed and accessible (for example, it appears in the available skills list or its SKILL.md is present). If it is, use it directly. If it is not installed, install it via the skills CLI, if available, with npx / bunx : Replace <skill name with the skill you need (for example, neon object storage , neon functions , or neon ai gateway ). Useful flags: g — install globally instead of into the current project. y — non interactive mode (skip prompts). a <agent name — pick the target agent(s) for non interactive mode. For example, to install the object storage skill globally for a specific agent without prompts: If you don't have access to the skills CLI, you can visit https://neon.com/.well known/agent skills for a registry of all available Neon skills and fetch them manually. Updating Skills Keep the skills up to date: for every new session, update them so you are working with the latest best practices. Use the same method that was used to install them. With the skills CLI, run the install command above with update in place of add , or run npx skills update to update all Neon skills. If the skills were installed via a plugin, they are updated automatically. Getting Started with Neon Before npx neon@latest init agent , check whether the CLI is already authenticated: NEON API KEY is set npx neon@latest profile list o json lists a profile whose account is not A DEFAULT row with account: " " and file: "missing" is not an account. If neon is not installed, or npx neon@latest profile list cannot run, that is not an account. If none of those hold, follow [Starting without a Neon account]( starting without a neon account). The easiest way to get started with Neon is to use our CLI and the project bootstrap wizard: Use the agent flag to run in a non interactive, state machine mode. This init command will guide you through installation of suggested Neon development tools. Everything is customizable. The defaults are: Neon CLI installed globally Neon MCP server installed globally Neon Agent skills installed into the project If init is run in an empty project, it will run the bootstrap command, offering to install one of our project templates. Getting Started with the Neon CLI Prefer the CLI over the MCP server unless the user instructs otherwise, the CLI is unavailable or blocked in your environment, or it is not authenticated, since it provides more capabilities, including deploying Neon Functions. The above init command will install the Neon CLI, but the CLI can also be installed manually with npm i g neon or bun i g neon . For full CLI installation options, see https://neon.com/docs/cli/install.md Useful CLI Commands These commands are included in the init command but can be run manually as needed. 1. neon link — Interactively links the workspace to a Neon org, project, and branch, writing the IDs to a git ignored .neon file. Run once per project. Once linked, project and branch scoped commands no longer need project id or branch (for example, neon branch list ). 2. neon checkout <branch name — Pins a different branch in .neon , creating it if it doesn't exist yet, and pulls that branch's env. It drives the [Branch First Dev Flow]( branch first dev flow) described below. 3. neon config init — Initializes a neon.ts file, which declares how you provision and manage Neon services, in the root of the project. 4. neon env pull — Fetches the current branch's Neon environment variables ( DATABASE URL , …) into your existing .env , or .env.local if you don't have one (override the target with file ). No branch ID needed; it reads .neon . link and checkout run this for you by default , so you rarely call it directly. Without neon.ts it pulls the vars of every service the branch actually has (Postgres, plus Neon Auth, the Data API, and bucket AWS once provisioned); with neon.ts it pulls only the services declared there and errors if the branch is missing one — and the AI Gateway vars are never pulled unless neon.ts declares aiGateway . Getting Started with the Neon MCP Server The above init command will install the Neon MCP server globally, but it can also be installed manually using: npx y add mcp https://mcp.neon.tech/mcp g n Neon y a <agent name or through your IDE plugin. For all available plugins, see: https://neon.com/docs/ai/ai agents tools.md For full MCP server installation options, see https://neon.com/docs/ai/connect mcp clients to neon.md Useful MCP tools to initialize a project: list projects — Lists the first 10 Neon projects in your account, providing a summary of each project. If you can't find a specific project, increase the limit by passing a higher value to the limit parameter. create project — Creates a new Neon project in your Neon account. A project acts as a container for branches, databases, roles, and computes. get connection string — Returns your