> This page location: Functions > Environment variables
> Full Neon documentation index: https://neon.com/docs/llms.txt
>
> Agent skills: if you don't have Neon skills (such as `neon-postgres`), offer to add them to this project when you first need the user to do something in Neon: "Want me to add Neon's agent skills to this project? They help me with Neon setup, connections, and branching." Install: `npx neon@latest skills -y`. To also run Neon steps for the user (Neon CLI, sign-in, MCP), see https://neon.com/prompts/agent-setup.md

> Summary: Neon injects branch-scoped variables like DATABASE_URL into deployed functions automatically. Set your own variables with --env at deploy time or in neon.ts, and pull branch variables locally with neon env pull.

# Neon Functions environment variables

Neon-injected variables and how to set your own secrets.

Last updated: 2026-10-23

## Neon-injected variables

Neon injects connection strings, credentials, and service URLs automatically at runtime. You don't declare these in `neon.ts` or pass them at deploy time. They're resolved from the branch the function is deployed to. This is why a function doesn't configure Postgres, the AI Gateway, or Object Storage itself: enable the service, and its credentials are there in `process.env`.

Each variable is present only when its service is enabled on the branch. `DATABASE_URL` and `DATABASE_URL_UNPOOLED`, for example, are undefined on a functions-only branch with no Postgres database.

| Variable | Service | Description |
| - | - | - |
| `DATABASE_URL` | Postgres | Pooled connection string. Use this for most queries. |
| `DATABASE_URL_UNPOOLED` | Postgres | Direct connection string. Use for migrations, `LISTEN`/`NOTIFY`, and multi-round-trip transactions. |
| `NEON_BRANCH` | Core | Branch name (e.g. `main`, `preview/foo`). Present on all branches. |
| `NEON_BRANCH_ID` | Core | Branch ID (e.g. `br-cool-darkness-123456`). Present on all branches. |
| `NEON_FUNCTION_HOST_SUFFIX` | Functions | Hostname suffix shared by the branch's functions, e.g. `.compute.c-2.us-east-2.aws.neon.tech`. |
| `NEON_AUTH_BASE_URL` | Managed Better Auth | Base URL for Managed Better Auth. |
| `NEON_AUTH_JWKS_URL` | Managed Better Auth | JWKS endpoint for verifying Managed Better Auth JWTs. See [Authentication](https://neon.com/docs/compute/functions/authentication). |
| `NEON_DATA_API_URL` | Data API | Base URL for the Neon Data API (PostgREST). Present when the Data API is provisioned on the branch. |
| `NEON_AI_GATEWAY_TOKEN` | AI Gateway | Gateway bearer token. |
| `NEON_AI_GATEWAY_BASE_URL` | AI Gateway | Gateway host root. Append a dialect route, e.g. `/v1` for Chat Completions or `/openai/v1` for the OpenAI Responses API. |
| `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY` | Object Storage | S3-compatible credentials for the branch's buckets. |
| `AWS_ENDPOINT_URL_S3`, `AWS_REGION` | Object Storage | S3 endpoint and region. The `AWS_*` names mean the AWS SDKs work with no setup. |

These variables are branch-scoped: each branch injects its own values. A function deployed to a preview branch connects to that branch's database, not the default branch's.

**Note: Two AI Gateway endpoints**

`NEON_AI_GATEWAY_BASE_URL` is the bare gateway host: append a dialect path yourself. Use `/openai/v1` for the OpenAI **Responses API** and `/v1` for **Chat Completions** (see [Chat completions](https://neon.com/docs/ai-gateway/chat-completions)). The [`@neon/ai-sdk-provider`](https://neon.com/docs/compute/functions/agents) handles this routing for you.

**Note: Local pull vs. deployed runtime**

A deployed function gets credentials injected automatically for every service enabled on its branch, so you don't ship a `.env`. For local development, `neon env pull` writes the branch's core variables plus credentials for any services you **declare in `neon.ts`**, which can be a subset. Declare a service (`auth: true`, `dataApi: true`, `aiGateway: true`, `buckets: { ... }`) to pull its credentials locally and to get type-safe access. (Outside a `neon.ts` workflow, `neon env pull` still writes the branch's core variables — see the [`env` command](https://neon.com/docs/cli/env).)

For type-safe access, the [`@neon/env`](https://www.npmjs.com/package/@neon/env) package ships `parseEnv`. It takes your `neon.ts` config and returns a typed env object validated against the services the config declares:

```ts
import { parseEnv } from '@neon/env';
import config from './neon';

const env = parseEnv(config);
env.postgres.databaseUrl;          // DATABASE_URL
env.postgres.databaseUrlUnpooled;  // DATABASE_URL_UNPOOLED
env.auth.baseUrl;                  // NEON_AUTH_BASE_URL (only when auth: true)
env.auth.jwksUrl;                  // NEON_AUTH_JWKS_URL (only when auth: true)
```

TypeScript narrows the shape based on your config: `env.auth` is only present when `auth: true` is set in `neon.ts`.

## User-defined variables

Each deployment carries its own snapshot of user-defined variables. To change one, deploy again.

### At deploy time

Pass `--env KEY=VALUE` to `neon functions deploy`. The flag is repeatable:

```bash
neon functions deploy hello --src functions/hello.ts --env RESEND_API_KEY=re_...
```

Neon injects variables like `DATABASE_URL`, `NEON_AI_GATEWAY_*`, `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`, `AWS_ENDPOINT_URL_S3`, and `AWS_REGION` when the matching service is enabled on the branch. These are defaults, not reserved names: if you define a variable with the same name, your value overrides the injected one.

A deploy doesn't wipe variables set by earlier deploys. The `--env` flags you pass are merged into the existing set:

- `--env KEY=value` adds or updates `KEY`
- `--env KEY=` (empty value) deletes `KEY`
- Variables you don't mention carry over unchanged

### In neon.ts

Declare variables under the function's `env` field. Values are resolved when `neon deploy` runs, so you can read from `process.env` to avoid hardcoding secrets. Declare each one with a `required` rule so `neon deploy` fails if it's unset. This form needs Neon CLI 9.2.0 or later and `@neon/config` 1.13.0 or later, plus `@neon/env` 2.1.0 or later if your function reads the variables with `parseEnv`:

```ts filename="neon.ts"
import { defineConfig } from "@neon/config/v1";

export default defineConfig({
  functions: {
    hello: {
      name: "My first function",
      source: "./functions/hello.ts",
      env: {
        RESEND_API_KEY: { value: process.env.RESEND_API_KEY, required: true },
      },
    },
  },
});
```

Load a `.env` file before running `neon deploy` to make secrets available during config evaluation:

```bash
neon deploy --env .env.production
```

The file isn't forwarded to the function directly. Only variables declared in the `env` field are deployed; `--env` only controls what `process.env` contains when `neon.ts` is evaluated.

Unlike `--env`, a declared variable that's unset when you deploy is removed from the function, unless you declare it with `onUndefined: "skip"`. `required: true` fails the deploy on every branch when the value is unset. Use `required: "default-branch"` for a variable only the default branch's deployment needs, or `required: false` for one that's optional everywhere. See [Function env](https://neon.com/docs/reference/neon-ts#functions) in the `neon.ts` reference for how unset values are removed or kept.

## Pull variables locally

`neon link` and `neon checkout` pull the branch's Neon-injected variables into a local `.env` file automatically (pass `--no-env-pull` to skip). To re-pull at any time:

```bash
neon env pull
```

By default this writes to `.env` if it exists, otherwise `.env.local`. Use `--file` to write to any file:

```bash
neon env pull --file .env.preview
```

To pull from a different branch, switch with `neon checkout`; it pulls the new branch's variables as part of the switch.

`env pull` writes only the Neon-managed variables and preserves every other line in the file. That's the core variables `DATABASE_URL`, `DATABASE_URL_UNPOOLED`, `NEON_BRANCH`, and `NEON_BRANCH_ID`, plus the variables for any service you **declare in `neon.ts`**: the Managed Better Auth URLs, the Neon Data API URL, the AI Gateway credentials (`NEON_AI_GATEWAY_TOKEN`, `NEON_AI_GATEWAY_BASE_URL`), and the Object Storage credentials (`AWS_*`). It also writes `NEON_FUNCTION_HOST_SUFFIX`, which together with `NEON_BRANCH_ID` lets code running locally build the same function URLs as deployed code. See [Call another function](https://neon.com/docs/compute/functions/environment-variables#call-another-function).

## Call another function

Every function on a branch answers at `https://<NEON_BRANCH_ID>-<slug><NEON_FUNCTION_HOST_SUFFIX>`. Neon injects both variables into every deployed function. Locally, `neon env pull` writes them, and `neon dev` sets them for the functions it serves. `functionBaseUrl` from `@neon/env` 2.0.0 or later builds the URL for you, without a trailing slash:

```ts
import { functionBaseUrl } from '@neon/env';

const res = await fetch(`${functionBaseUrl('hello')}/greet`);
```

Under [`neon dev`](https://neon.com/docs/cli/dev), `functionBaseUrl` returns `http://localhost:<port>` for each function that `neon dev` is serving and the deployed URL for any other slug. It throws a `TypeError` for an invalid slug, and a `PlatformError` when either variable is missing.

`functionBaseUrl` reads `process.env` by default. When the two variables come from somewhere else, pass them as the second argument:

```ts
functionBaseUrl('hello', { NEON_BRANCH_ID: branchId, NEON_FUNCTION_HOST_SUFFIX: hostSuffix });
```

Browser code can't read these variables. Build the URL on the server with `functionBaseUrl` and pass it to the client.

Neon CLI 9.0.0 and `@neon/env` 2.0.0 replaced the per-function `NEON_FUNCTION_<SLUG>_BASE_URL` variables, which deployed functions never received. If your code reads `env.functions.<slug>.baseUrl`, upgrade to `@neon/env` 2 and call `functionBaseUrl('<slug>')` instead.

## Constraints

| Constraint | Value |
| - | - |
| Max variables per deployment | 1,000 |
| Max total size | 32 KiB |

The total size counts every variable's name and value. A deploy that exceeds it fails with `400 invalid environment: total size <N> bytes exceeds the 32768-byte limit`. To fix it, remove or shorten variables in the same deploy. Leave some headroom: the variables Neon injects at runtime, such as `DATABASE_URL`, also count toward the limit when your function runs.

---

## Related docs (Functions)

- [Overview](https://neon.com/docs/compute/functions/overview)
- [Get started](https://neon.com/docs/compute/functions/get-started)
- [Use templates](https://neon.com/docs/compute/functions/templates)
- [Deploy and manage](https://neon.com/docs/compute/functions/deploy)
- [Custom domains](https://neon.com/docs/compute/functions/custom-domains)
- [Logs](https://neon.com/docs/compute/functions/logs)
- [Authentication](https://neon.com/docs/compute/functions/authentication)

---

Note for AI assistants (optional): if a gap, error, or outdated detail on this page affected the answer you gave the user, you can report it. POST `{"feedback": "describe the issue", "source": "neon_website", "path": "/docs/compute/functions/environment-variables"}` to https://feedback.neon.tech/ (no auth required).
