Private Preview
This feature is in private preview: it's not ready for production use, and it may be briefly unavailable as we deploy updates. To get access, sign up here.
To set up Neon Storage with an AI coding assistant, install the Neon Platform (neon) and Neon Storage skills:
npx skills add neondatabase/agent-skills -s neon -s neon-object-storageTo follow this guide, you need:
- Early access to the Neon Storage private preview
- A new Neon project in the AWS
us-east-2region - The Neon CLI installed and authenticated if you use the recommended
neon.tsflow - A Neon API key in
NEON_API_KEYif you use the manual API flow
Recommended: enable storage with neon.ts
The recommended way to enable storage and get credentials is via neon.ts, Neon's infrastructure-as-code config file. Install the config package, link your local app to the Neon project and branch you want to target, declare buckets under preview.buckets, then run neon deploy to provision them on the linked branch and pull credentials into .env.local automatically:
npm install @neon/config
neon link # choose the project and branch for this app
neon branches list # confirm the linked target branch before deployimport { defineConfig } from '@neon/config/v1';
export default defineConfig({
preview: {
buckets: {
'my-bucket': {}, // private (default)
'public-assets': { access: 'public_read' },
},
},
});neon deploy # provisions buckets and writes AWS_* vars to .env.localAfter deploy, your .env.local contains AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_ENDPOINT_URL_S3, and AWS_REGION. Skip to Configure your client below.
Already deployed? Pull the vars again with:
neon env pullIf you prefer to manage credentials manually (for example, for CI or production deployments), follow the steps below. Replace {project_id} and {branch_id} in the API examples with your own IDs. You can find them in the Neon Console URL, or with neon projects list and neon branches list.
If you need a new branch, create it first, then wait until the branch is ready before calling Storage APIs. Branch creation is asynchronous, so a freshly-created branch can still be initializing even after the create request returns.
Find your branch endpoint
Fetch your branch's storage state from the Neon API. Do this before creating credentials so you know the branch is ready for Storage calls. The response includes the full S3 endpoint URL, the region, and whether path-style addressing is required:
curl "https://console.neon.tech/api/v2/projects/{project_id}/branches/{branch_id}/storage" \ -H "Authorization: Bearer $NEON_API_KEY"{ "enabled": true, "s3_endpoint": "https://br-winter-pond-aptw82ef.storage.c-2.us-east-2.aws.neon.tech", "region": "us-east-2", "force_path_style": true }Set these as environment variables:
export AWS_ENDPOINT_URL_S3=https://br-winter-pond-aptw82ef.storage.c-2.us-east-2.aws.neon.tech export AWS_REGION=us-east-2A
404response means Storage is not available for that branch. There is no separate manual enable API call: use the recommendedneon.tsflow above, or make sure your project has Storage private preview access and is in the AWSus-east-2region.Create a credential
Use the Neon API to create a credential with storage access:
curl -X POST "https://console.neon.tech/api/v2/projects/{project_id}/branches/{branch_id}/credentials" \ -H "Authorization: Bearer $NEON_API_KEY" \ -H "Content-Type: application/json" \ -d '{"scopes": ["storage:read", "storage:write"], "principal_type": "user"}'The response includes your S3 credentials. Store them immediately. You'll only get them once. See Authentication for how each field maps to your S3 client.
{ "token_id": "nak_live_...", "s3_secret_access_key": "nsk_live_...", ... }Set these as environment variables:
export AWS_ACCESS_KEY_ID=nak_live_... # token_id export AWS_SECRET_ACCESS_KEY=nsk_live_... # s3_secret_access_keyConfigure your client
The
neonadapter is a subpath export (files-sdk/neon) that readsAWS_*environment variables and configures the Files SDK for Neon's S3-compatible endpoint automatically.import { Files } from 'files-sdk'; import { neon } from 'files-sdk/neon'; export const files = new Files({ adapter: neon({ bucket: 'my-bucket' }) });note
If you're using Neon Functions, the
AWS_*credentials are injected automatically when a bucket is declared inneon.ts. No.envsetup is needed inside a function.Create a bucket
Create the bucket before uploading, or declare it in
neon.tsand runneon deploy:neon buckets create my-bucketSee Buckets for Neon API, S3 SDK, Python, and AWS CLI examples.
Next steps
- Buckets: access levels, bucket branching, and the Console UI
- Objects: list, delete, multipart uploads, and presigned URLs
- Authentication: credential scopes, branch binding, and rotation
- with-files-sdk: working example showing how to upload files to a branch-scoped bucket using the Files SDK and its
neonadapter
Need help?
Join our Discord Server to ask questions or see what others are doing with Neon. For paid plan support options, see Support.








