> ## Documentation Index
> Fetch the complete documentation index at: https://nango.dev/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Environments

> Organize your integrations & data with environments

Environments help you segment your integration configuration and customer data across different stages of your development lifecycle.

## Overview

Each environment in your Nango account is completely isolated with its own:

* Integration configurations
* [Functions](https://nango.dev/docs/guides/functions/functions-guide.md)
* [Connections](https://nango.dev/docs/guides/auth/auth-guide.md)
* Environment-specific settings

> [!NOTE]
>
> Each Nango account comes with **dev** and **prod** environments by default. Additional environments are available depending on your [pricing plan](https://www.nango.dev/pricing). Create them from the environment dropdown in the dashboard, or with the [Create an environment API](https://nango.dev/docs/reference/backend/http-api/environments/create.md).

## Production environments

Any environment can be designated as a production environment. This affects how team members interact with it based on their [role](https://nango.dev/docs/guides/platform/security.md#team-and-roles).

**To mark an environment as production:**

1. Open the environment settings (gear icon in the top navigation)
2. Toggle the **Production environment** switch

> [!NOTE]
>
> Only **Full Access** team members can toggle the production flag. Once an environment is marked as production, **Support** members get read-only access to it, and **Contributor** members lose access entirely.

By default, the `prod` environment created with your account is already marked as production.

## Engineering collaboration

Use a **shared non-production environment** (usually `dev`) for day-to-day engineering work. The team shares integrations and the baseline function set. For local webhook testing, each engineer creates their own connections with a webhook URL override (see below).

### Local webhooks on a shared environment

Keep the environment webhook URL pointed at your shared app (or staging backend). To receive webhooks from Nango locally, create connections with a [per-connection `webhook_url` override](https://nango.dev/docs/guides/platform/webhooks-from-nango#override-webhook-urls-per-connection) pointing at your local webhook endpoint (for example via [ngrok](https://ngrok.com/)).

One convenient pattern is to read the override from an optional env var, so the same connect-session code works locally and when the var is unset. For example, set `NANGO_CONNECTION_WEBHOOK_URL` in your local `.env` to that URL and leave it unset elsewhere:

```ts theme={null}
const webhookUrl = process.env.NANGO_CONNECTION_WEBHOOK_URL; // e.g. https://<you>.ngrok.app/webhooks-from-nango

const session = await nango.createConnectSession({
    tags: {
        end_user_id: '<END-USER-ID>'
    },
    allowed_integrations: ['<INTEGRATION-ID>'],
    ...(webhookUrl && { webhook_url_override: webhookUrl })
});
```

When the var is set, new connections from that session route webhooks to your machine without changing the environment webhook URLs.

### Local function deploys on a shared environment

A full `nango deploy` reconciles every function in the environment. On a shared collaborative environment, that can overwrite teammates' deploys. Deploy only what you changed:

```bash theme={null}
nango deploy <env> <integration>/<folder>/<file>.ts   # one function, e.g. github/tools/get-issue.ts
nango deploy --integration <id> <env>                 # all functions for one integration, including event functions
```

Deploying a single file never deletes other functions. Event functions can only be deployed with their integration or the whole project.

Reserve full deploys for environments where the repo is the sole source of truth (for example staging or prod). See the [CI/CD guide](https://nango.dev/docs/guides/functions/ci-cd.md).

### One environment per engineer

You can give each engineer their own environment for full isolation. You then need to recreate integrations, connections, and settings in each environment yourself; that also means more API keys to manage and config that tends to drift over time. A shared `dev` environment avoids that overhead for most teams.

## Best practices

**Mirror your application environments**

We recommend creating Nango environments that match your application's deployment stages. For example:

* Development / local → dev environment
* Staging → staging environment
* Production → prod environment
* Demo → demo environment

**Deploy to specific environments**

When you deploy [Functions](https://nango.dev/docs/guides/functions/functions-guide.md), you always target a specific environment. This ensures changes are tested before reaching production.

## Related guides

* [API keys](https://nango.dev/docs/reference/backend/http-api/api-keys.md) - scope keys per environment.
* [Create an environment](https://nango.dev/docs/reference/backend/http-api/environments/create.md) - create environments via API.
* [CI/CD](https://nango.dev/docs/guides/functions/ci-cd.md) - deploy functions safely across environments.
* [Webhooks from Nango](https://nango.dev/docs/guides/platform/webhooks-from-nango.md) - environment and per-connection webhook URLs.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.