Build and operate multi-tenant AI agent platforms on Neon. Use this skill whenever the user is designing an agent/app builder, provisioning a Neon project or database per user/app/agent run, managing thousands of tenant projects, separating sponsored free users from paid customers, moving projects between orgs, choosing personal vs organization vs project-scoped API keys, tracking fleet consumption or Agent Plan costs, creating compound checkpoints that combine DB snapshots with source revisions/secrets/deploy metadata, or orchestrating snapshot/restore flows for generated apps. Also use it for Neon Agent Program, Agent Plan, org/project limits, HIPAA, co-marketing, support, or neondatabase/neon-for-agent-platforms examples.
Build and operate multi-tenant AI agent platforms on Neon. Use this skill whenever the user is designing an agent/app builder, provisioning a Neon project or database per user/app/agent run, managing thousands of tenant projects, separating sponsored free users from paid customers, moving projects between orgs, choosing personal vs organization vs project-scoped API keys, tracking fleet consumption or Agent Plan costs, creating compound checkpoints that combine DB snapshots with source revisions/secrets/deploy metadata, or orchestrating snapshot/restore flows for generated apps. Also use it for Neon Agent Program, Agent Plan, org/project limits, HIPAA, co-marketing, support, or neondatabase/neon-for-agent-platforms examples.
Companion to **neon-postgres** (install that first). This skill covers
fleet-scale control plane for the Neon Agent Program: dual-org layout, project
transfer, per-tenant provisioning, compound checkpoints, consumption, and
commercial terms.
For connection strings, drivers, ORMs, branching tutorials, Auth in apps, Data
API, and MCP, use **neon-postgres** and Neon docs.
Scope
Use **neon-postgres** for general Neon usage. Use this skill when the
question involves:
Dual-org economics and API keys (personal, organization, project-scoped)
Project-per-tenant provisioning and transfer
Fleet-wide snapshot/restore orchestration and housekeeping
Compound checkpoints
Consumption polling for metered fleets
Agent Plan commercial terms (with links, not invented numbers)
With **neon-postgres** and this skill loaded, you have enough context for
platform-level Neon work: dual-org layout, provisioning a project for a new
tenant, compound checkpoints, org-wide consumption polling, and
transfer/upgrade flows—without the user pasting long documentation.
Where runnable examples live: TypeScript samples run from this skill’s scripts/
directory (package.json, npm run …). The **references/** directory
keeps markdown guides beside the runnable examples;
MANAGEMENT_API_SAMPLES.md
is the script catalog and env map. The human Quick start is the root
README.
Gotchas
Non-obvious facts agents often get wrong:
Checkpoints are compound records. A tenant checkpoint includes source
revision + Neon snapshot/branch + secrets/env version + deploy URL + agent
metadata. Do not equate "checkpoint" with "Neon branch" alone. See the
compound checkpoints doc.
Cross-org transfer needs a personal API key (org keys only work
inside one org). Projects with GitHub or Vercel integrations in Neon cannot
be transferred; the API returns 422 (Transfer projects).
After a finalized snapshot restore, the active branch ID changes. Poll
operations to completion before reconnecting. Delete orphaned (old) branches
to avoid storage cost.
Billing-aligned usage: prefer
GET /api/v2/consumption_history/v2/projects over legacy consumption
endpoints. GET /api/v2/consumption_history/account is deprecated with a
planned sunset of 2026-06-01; migrate to the v2 per-project endpoint
(legacy consumption guide).
Snapshot schedules are not provided on Agent Plan. Partners implement via
snapshot API + their own scheduler.
Rates and caps: never invent dollar amounts or limits. Confirm on live
neon.com docs.
Agent Plan and two organizations
Partners run two Neon organizations:
Org
Role
Sponsored free org
Free-tier end users (within program rules)
Paid org
Paying customers (metered per Agent Plan)
Key points:
Dollar rates, credits, and project caps come only from the live
Agent Plan and
neon.com/agents. Do not invent numbers.
Organization API key: automation inside one org (create project, set
quotas).
Personal API key: required to transfer a project between orgs when a
customer changes tier, then PATCH quotas to match the new tier.
Project-scoped API key:member-level access to one project only—narrower than an org key and useful for per-tenant runtime or automation that must not touch the rest of the org. Cannot create new projects org-wide; invalid if the project is transferred out of the org.
Project-per-tenant is Neon's documented fleet pattern: each tenant you
provision for (an end user, a customer app, or an agent workload)
gets its own dedicated Neon project. That project is the isolation boundary
for branches, databases, roles, and computes—not a shared
Postgres cluster where you only partition by schema.
Isolation and billing: Separate projects give complete data and resource
isolation between tenants, keep consumption limits and billing
straightforward at project scale (aligned with Agent Plan metering elsewhere in
this skill), and match how the Neon Management API and Console are structured
(project-scoped create, quota, and lifecycle calls).
Staging and production
For each tenant project, treat staging versus production (and ephemeral
previews) as branch- and snapshot-driven lifecycle inside that
project—use Snapshots and database versioning and Sandbox and preview
databases below for fleet orchestration, not a second project by default.
Agent and app builders: separate your platform's environments (for
example how you host the builder or control plane) from each tenant's staging
and production branches—avoid conflating "our production service" with "the
tenant's production branch" in ledgers and automation.
Some embedded products also split an end customer's production and
development Neon assets across separate orgs for trust, keys, and billing
boundaries; when that applies, read Isolation beyond branches (project and org
edge cases) next.
Isolation beyond branches (project and org edge cases)
Use project- or org-level splits when tenant scope or trust needs go
beyond branch- and snapshot-first staging and production in Fleet shape.
Embedded products may isolate an end customer's production versus
development databases across separate Neon orgs, not only branches—tighter
billing, org API keys, and console boundaries while you still manage branches
within each org.
Project-level isolation (multiple projects per tenant or workload):
Stronger blast radius if a connection string or role is compromised—one
leak should not span unrelated workloads.
Separate operational lifecycles (for example a disposable analytics or
migration sandbox versus production data) when automation or ownership would
otherwise collide in one Postgres.
Different teams or automation with conflicting migration or admin rights.
Harder compliance or data-mixing rules where a single database must not
host combined workloads.
Each extra project adds fleet surface area: more API keys, more consumption
rows, more housekeeping, and higher operational cost—keep project-per-tenant
as the default unless a boundary above clearly applies.
Org-level isolation (beyond sponsored free versus paid):
The two-organization layout in Agent Plan and two organizations is
the commercial split (free-tier users versus paying customers). That pattern
can stack with an embedded product split: for example prod org versus dev
org per end customer so playground databases never share org scope with shipped
production. Keep a clear internal map of which org owns which environment and
tier.
Separately, partners sometimes need additional Neon orgs or accounts for
contracting (enterprise “their org only”), reseller or MSP models, or
geographic or legal separation—product defaults and limits belong on live docs;
do not invent caps.
Organization API keys are scoped to one org. Cross-org moves use a
personal API key and project transfer, as in Gotchas—do not assume an
org key can operate across orgs. Project-scoped keys are further limited to a
single project (API keys).
Embedding hygiene:
Map each platform service (control plane, tenant runtime, billing or
consumption jobs) to least-privilege keys; do not reuse production keys in
sandboxes at the wrong layer.
When prod and dev for an end customer live in different Neon orgs, scope
automation per org (typically one organization API key per org) and persist
org_id with project_id / branch_id so jobs and restores target the correct
side.
Keep your ledger (project_id, branch_id, org, checkpoint metadata)
aligned with the isolation layer you chose so restores, transfers, and audits
stay consistent.
Snapshots and database versioning
For snapshot semantics, active-branch patterns, and restore tutorials, defer to
**neon-postgres** and
AI database versioning.
Here, emphasize tenant fleets:
Persist snapshot and branch IDs per tenant in your ledger. Tie each to
non-Neon state via
compound checkpoints.
After finalized restores, branch IDs change and orphaned (old) branches
accumulate. Automate cleanup and update stored IDs.
Poll operations to completion before reconnecting tenant apps.
Product semantics (snapshot counts per tier, Beta pricing dates) change.
Confirm on Agent Plan docs.
Typical platform-level checkpoint triggers:
Before promoting generated schema changes for a tenant
Start or end of an agent run that mutates a tenant's database
Before destructive migrations or customer-visible restore actions
Use this when a partner needs per-tenant preview or sandbox databases for
generated apps. ("How do I create a branch?" for a single app goes to
**neon-postgres**.)
Track project_id / branch_id per customer / agent run when spinning
previews via the Management API.
Branch and storage counts scale with fleet size. Monitor caps and
garbage-collect idle previews.
Short suspend_timeout_seconds on preview computes reduces cost.
Pair branch/snapshot lifecycle with secrets rotation and deploy URLs via
compound checkpoints.
Use GET /api/v2/consumption_history/v2/projects for billing-aligned fields.
Legacy endpoints differ. GET /api/v2/consumption_history/account is
deprecated (sunset 2026-06-01); use v2 per-project metrics instead
(legacy guide).
All scripts use @neondatabase/api-client only. Shared
utils.ts
polls async operations. For SQL access from app code (drivers, pooling, ORMs),
use **neon-postgres**.
