Neon Object Storage is S3-compatible object storage built into the Neon backend for apps and agents. Every branch gets its own isolated storage namespace. Use any AWS S3-compatible SDK or tool. Point it at your branch endpoint and authenticate with your Neon credential. No separate storage account or cloud credentials required.
During the beta, object storage is currently available in AWS US East (Ohio) (
aws-us-east-2) and AWS Europe (Frankfurt) (aws-eu-central-1), and is free to use, subject to usage limits. Support is expanding toward all regions. See plans and pricing for storage and egress rates.
- Branches with your database. Each branch has its own view of storage. Test file uploads and deletions in preview branches without touching production data.
- Standard S3 SDKs. The AWS SDK for JavaScript, boto3, the AWS CLI, the Files SDK, and any other S3-compatible tool works out of the box.
- Two access modes.
privatebuckets require authentication for all operations.public_readbuckets allow anonymous reads with authenticated writes. - One credential system. The same Neon credential system used by AI Gateway and Functions.
Get started
Quickstart
Create a credential, configure a client, and upload your first file.
Buckets
Create and manage buckets, set access levels, and understand how buckets branch.
Objects
Upload, download, list, delete, and generate presigned URLs for objects.
Authentication
Understand how Neon credentials map to S3 access keys.
Logs
View, search, and download a bucket's logs in the Console.
Starter templates
The examples repository includes templates that use Neon Object Storage. Each declares its bucket in neon.ts and provisions it with neon deploy, which also injects the S3 credentials, so there are no secrets to copy. A couple to start with:
files-sdk is a standalone script that uploads local files to a public_read bucket with the Files SDK and its neon adapter, then prints presigned URLs. A minimal example of the storage API on its own:
neon bootstrap --template files-sdkai-sdk is a chat agent on a Neon Function that generates images, stores each one in a private bucket with the AWS S3 SDK, records its key and metadata in Postgres, and serves it back through a presigned URL. Shows object storage and the database branching together:
neon bootstrap --template ai-sdkLimits
During the beta, the following limits apply:
| Limit | Value |
|---|---|
| Object size (maximum) | 5 GiB, whether uploaded in a single request or with multipart upload |
| Free plan object storage | 5 GB per project (rates) |
Two limits are behavioral rather than fixed numbers:
- Region: object storage is available in AWS US East (Ohio) (
aws-us-east-2) and AWS Europe (Frankfurt) (aws-eu-central-1). Support is expanding toward all regions. - Rate limiting: requests may be throttled during heavy use, returning a
503 SlowDownresponse. Back off and retry. See Connection and performance errors.
When billing begins, paid plans follow standard S3 limits: individual objects up to 5 TB, with a 5 GB maximum for a single-request upload. Use multipart upload for larger objects; AWS recommends it for anything over 100 MB. Storage-volume limits apply to the Free plan only; paid plans have no fixed limit on total storage or number of objects, which is metered per GB (see plans and pricing).
For S3 API and feature limitations (as opposed to usage limits), see Known limitations.
Need help?
Join our Discord Server to ask questions or see what others are doing with Neon. For paid plan support options, see Support.