# Instances / Environments When creating a new application within Clerk, you are provided with two instances: `Development` and `Production`. These instances vary slightly and should only be used appropriately. ## Development instance A `Development` instance is Clerk's default instance type and has characteristics that allow it to be more useful for local development. To facilitate development and local authentication, `Development` instances have a more relaxed security posture and are not suitable for production workloads. Some notable examples of `Development`-only characteristics in a Clerk application are: - A `Development` banner is shown prominently in the Clerk Dashboard to make clear you're managing or configuring non-production data. - Email and SMS templates are prefixed with the environment type to prevent against using `Development` instances for production purposes. - Some social connections use shared credentials by default. - [The Account Portal](https://clerk.com/docs/guides/account-portal/overview.md) will use a Clerk development domain that ends with `accounts.dev` instead of your app's production domain. - OAuth consent screens will show the development domain that ends with `accounts.dev` instead of your production domain. - Search engines will not be able to crawl and index your application. - Development instances are capped at 100 users, and user data can not be transferred between instances. - The architecture of Clerk's sessions management is different in development environments compared to production environments, due to the need to communicate cross-domain between `localhost` and `.accounts.dev`. The `__clerk_db_jwt` object is _only_ used in development environments. For more specific details on the differences between Clerk's session management architecture in development and production environments, see the [technical breakdown below](#session-architecture-differences). > All paid functionality is available in a `Development` instance. However, when you deploy your application to `Production`, you will be asked to upgrade to a `Pro` account if you are using paid features. See [our pricing page](https://clerk.com/pricing) for full details. ## Production instance A `Production` instance is the more robust option of Clerk's instance types. `Production` instances are meant to support high volumes of traffic and by default, have a more strict security posture. Some notable differences between `Production` and `Development` instances in a Clerk application are: - You must associate a production domain within the Clerk Dashboard - You are required to provision your own SSO credentials When deploying to production, you must first activate your `Production` environment. See the [Deploying to Production](https://clerk.com/docs/guides/development/deployment/production.md) guide to learn about the process and avoid common pitfalls. ## Staging environments Staging environments enable you to internally test and demo changes to your application or website before deploying them to production. Currently, Clerk only offers **Development** and **Production** instances. Official support for **Staging** instances is still on the [roadmap](https://feedback.clerk.com/roadmap?id=de417dd1-fa2e-4997-868f-4c9248027e7d). However, you can set up a "staging environment" by creating a separate Clerk application with a separate domain. Creating a separate Clerk application will prevent you from using live production environment data in your staging environment. > When you use a separate Clerk application for your staging environment, changes to this application **will not be automatically mirrored** in your main application for your production environment. You must manually make these changes yourself if you want them to be reflected in both applications. ### Set up a staging Clerk application The following steps will help you set up a new Clerk application with a staging-specific domain: 1. **Set up a subdomain** - This will be your staging domain. For example, if your domain is `my-site.com`, you could use `staging.my-site.com`. 2. **Create a new Clerk app** - Your staging environment will connect to this app instead of your main one. See [the Clerk quickstart guide](https://clerk.com/docs/getting-started/quickstart/setup-clerk.md) to learn how to create a Clerk app. 3. **Deploy and configure your staging app's production instance** - Using production API keys will make your staging app more secure. Follow the [Deploy to production](https://clerk.com/docs/guides/development/deployment/production.md) guide to do so. ### Alternatives #### Preview environments While staging environments are typically long-lived, preview environments are typically generated on-demand for specific pull requests. See [the section on using Clerk in a preview environment](https://clerk.com/docs/guides/development/managing-environments.md#preview-environments-2) to learn about your options. #### Shared production credentials If you would like to share settings and data between your production and staging environments, see [the dedicated guide](https://clerk.com/docs/guides/development/deployment/staging-alternatives.md). This is not recommended because you will be sharing a user table between your production and staging environments. ## Preview environments Some popular hosting providers like Vercel and Netlify offer preview deployments, which enable you to view changes to your site in a live environment before merging and deploying them to production. There are two high-level approaches to using Clerk in a preview environment: 1. Sharing production settings and user data 2. Using independent settings and user data ### Sharing production settings and user data To share production settings and user data with your preview environment, your preview environment must be hosted on the same root domain (but a separate subdomain) as your production application. The preview environment must also be configured to use the same API keys as your production environment. Generally, hosts have a special feature to host the preview environment on a subdomain of your root domain, for example: - **Vercel:** use the [Preview Deployment Suffix](https://vercel.com/docs/concepts/deployments/generated-urls#preview-deployment-suffix) feature. This feature is only available on Vercel's Pro and Enterprise plans. - **Netlify:** use the [Automatic Deploy Subdomain](https://docs.netlify.com/domains-https/custom-domains/automatic-deploy-subdomains/) feature. ### Using independent settings and user data There are two approaches to creating a preview environment with independent settings and user data: 1. **Easiest:** Use your host's provided preview domain, like \*.vercel.app or \*.netlify.app, with development API keys from Clerk. 2. Acquire an additional root domain for your preview environment, completely separate from your production application's root domain. #### Use your host's provided preview domain Configure the preview environment to use development API keys from Clerk. It is currently not possible to use Clerk production API keys with your host's provided preview domain. #### Acquire an additional root domain > To use an independent environment, it is critical that you acquire an additional domain. An independent environment will not work if it is configured on the same domain as your production application, even if it is on a separate subdomain. To use an additional root domain, you must first configure your host to deploy preview environments to that domain: - **Vercel:** use the [Preview Deployment Suffix](https://vercel.com/docs/concepts/deployments/generated-urls#preview-deployment-suffix) feature. This feature is only available on Vercel's Pro and Enterprise plans. - **Netlify:** use the [Automatic Deploy Subdomain](https://docs.netlify.com/domains-https/custom-domains/automatic-deploy-subdomains/) feature. You can configure this environment with either your development API keys (recommended) or you can create an additional production instance and use those production API keys. ## Session architecture differences > In order to understand this section, it's recommended to have a solid understanding of how Clerk's session management architecture works. For more information on this topic, check out the guide on [how Clerk works](https://clerk.com/docs/guides/how-clerk-works/overview.md). Clerk manages session state differently in production and development environments. In production, Clerk uses a [client token](https://clerk.com/docs/guides/how-clerk-works/overview.md#client-token) to represent the user's session. This client token is stored as an `HttpOnly` cookie (`__client`) on the [Clerk FAPI](https://clerk.com/docs/guides/how-clerk-works/overview.md#the-frontend-api) domain. Because, in production, FAPI is hosted on a subdomain of your application (e.g., `clerk.example.com`) via a CNAME record, your app's frontend and FAPI are on the same site. This allows the client token to be securely and reliably sent with each request from your frontend to FAPI using **same-site** cookies. However, in development, your app's frontend typically runs on a `localhost` domain, while FAPI for development instances is hosted on a domain ending with `accounts.dev`. As a result, requests from your app's frontend to FAPI are **cross-site**, and the client token cannot be securely and reliably stored or transmitted using cookies. > [!QUIZ] > Why can't the client token be securely and reliably stored and transmitted in a cookie when cross-site requests are made? > > *** > > In order for cookies to be sent cross-site, the cookie would need to be set with [`SameSite=None`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/Set-Cookie#none). In theory this would resolve the issue, but in reality, modern browsers are increasingly restrictive on cross-site cookie behavior due to the abuse of cookies for tracking and advertising. Safari specifically [does not support `SameSite=None` for cookies at all](https://support.apple.com/guide/iphone/browse-the-web-privately-iphb01fc3c85/ios) unless a browser flag is enabled. Other browsers also have restrictions around cross-site cookie behavior, which leads to a frustrating and unreliable experience for local development. To address these limitations, development instances use a different approach to maintain session state. An object called the "dev browser", which is linked directly to the client token within Clerk's internals, is used to maintain session state across the session lifetime, and is transmitted via querystring (`__clerk_db_jwt`) rather than via cookie. This strategy allows for a more reliable experience for local development, as it does not require the use of cross-site cookies. While this enables smooth local development workflows, it is not secure enough for production use. Including a sensitive value like the client token in a querystring is not a strong security practice, as it can be seen directly in server logs, browser history, internet providers' logs, and could be potentially intercepted by third-parties via malicious browser extensions or network interceptors. This is why the `__clerk_db_jwt` object is not used in production instances and the same-site cookie (`__client`) is used instead. --- ## Sitemap [Overview of all docs pages](https://clerk.com/docs/llms.txt)