1---
2title: Setup
3description: Prepare Neon credentials, service access, regions, and external dependencies before deploying with Alchemy.
4---
5
6Alchemy manages Neon resources using a management API key. Account plans, model
7access, third-party OAuth applications, and DNS remain separate setup steps.
8Complete the required sections below, then follow only the feature guides your
9application needs.
10
11## Create or select an account
12
13Sign in to the [Neon Console](https://console.neon.tech). Select the organization
14that should own the application and pay for its usage. Create an organization in
15Neon first if you need organization governance; Alchemy's governance resources
16manage an existing organization, not its creation or membership invitations.
17
18Copy the organization ID from **Organization Settings → General information**.
19Pass it as `orgId` when declaring an organization-owned `Neon.Project`. For a
20personal project, omit it. Confirm the deployment identity can both create and
21delete the resources it will own.
22
23## Choose a region and check service access
24
25Postgres availability does not imply that every backend service is available in
26the same region or on the same account. Check the current Neon documentation for
27[Functions](https://neon.com/docs/compute/functions/overview),
28[Object Storage](https://neon.com/docs/storage/overview),
29[Auth](https://neon.com/docs/auth/overview), and
30[AI Gateway](https://neon.com/docs/ai-gateway/overview) before choosing a region.
31
32The combined backend examples use Ohio (`aws-us-east-2`). Verify access on the
33intended account before deploying; this example is a region selection, not an
34entitlement grant:
35
36```typescript
37const project = yield* Neon.Project("Application", {
38 orgId: "org-example",
39 region: "aws-us-east-2",
40});
41```
42
43Changing a project's region requires replacement. Choose it before storing
44production data. Resources can incur normal Neon usage charges.
45
46## Create the deployment key
47
48Create a management API key following Neon's
49[API key guide](https://neon.com/docs/manage/api-keys). Select a key whose scope
50covers the entire lifecycle, including destruction, rather than only reads.
51
52| Key | Intended use | Boundary |
53| --- | --- | --- |
54| Personal management key | Deploy with the user's granted access | Inherits that user's permissions; an organization admin's personal key is required to create organization API keys |
55| Organization management key | Organization-wide automation | Broad administrative authority; keep it in the deployment environment |
56| Project-restricted organization key | Work within one existing project | Editor access does not include deleting the project or managing project access; unsuitable for a stack that owns that lifecycle |
57| Branch service credential (`Neon.Credential`) | Runtime storage or AI access | Separate from management keys; scopes cover the branch and descendants |
58
59Database passwords and end-user Auth JWTs are separate credentials again. Never
60place a management key in Function/Website `env`, browser code, or a runtime
61binding. See [governance permissions](/neon/governance#prepare-the-deployment-identity)
62for administrative controls.
63
64## Configure a local profile
65
66```sh
67pnpm exec alchemy profile edit --add Neon
68```
69
70Enter the key at the interactive prompt. Alchemy stores it under
71`~/.alchemy/credentials/<profile>/neon-stored.json`. Protect that directory and
72keep credentials out of version control. See [Profiles](/environments/profiles)
73for selecting a profile and using the same profile during deploy and destroy.
74
75## Configure environment credentials and CI
76
77Store `NEON_API_KEY` in your CI system's secret store and expose it only to the
78deployment job. Set `CI=true` in that job; Alchemy resolves credentials from the
79environment instead of requiring a local profile.
80
81A supplied `NEON_API_KEY` also takes precedence over a selected profile outside
82CI. If a command unexpectedly targets another account, check the process
83and dotenv environment before changing the profile. Avoid printing secrets or
84pasting them into shell history.
85
86## Register the provider
87
88Add `Neon.providers()` to your stack's provider layer. For example, when combining
89Cloudflare and Neon:
90
91```typescript
92import * as Cloudflare from "alchemy/Cloudflare";
93import * as Neon from "alchemy/Neon";
94import * as Layer from "effect/Layer";
95
96const providers = Layer.mergeAll(Cloudflare.providers(), Neon.providers());
97```
98
99Pass `providers` to your existing Stack configuration. The
100[upload tutorial](/neon/tutorial) provides a runnable Neon application rather
101than requiring you to assemble a stack from reference snippets.
102
103## Complete feature-specific setup
104
105| Feature | Manual prerequisite | Guide |
106| --- | --- | --- |
107| AI inference | Paid-plan access, approved credit purchase, and access to the selected model | [AI Gateway](/neon/guides/ai-gateway) |
108| Production sign-in | Verified email sender, SMTP credentials, OAuth apps/callbacks, and trusted production origins | [Production Auth](/neon/guides/production-auth) |
109| Governance | Existing organization, authorized deployment identity, membership IDs, and explicit approval for access/billing changes | [Organization governance](/neon/governance) |
110| Private database networking | Entitled organization, same-region AWS VPC endpoints, and private DNS | [Private networking](/neon/guides/private-networking) |
111| Custom HTTPS hostname | DNS control, DNS-only CNAME, compatible CAA policy, and HTTPS verification | [Custom domains](/neon/guides/custom-domains) |
112| Safe updates and cleanup | Durable state, protected backups, and consistent stack/stage selection | [State and recovery](/neon/guides/state-recovery) |
113
114These are optional feature prerequisites, not requirements to use Postgres. The
115upload tutorial does not require AI access or a credit purchase. Alchemy does not
116upgrade your plan or buy credits during deployment.
117
118## Prepare Function and Website builds
119
120Use Node.js 24 for the Function runtime and the package manager/toolchain required
121by your application. Repository examples also use Bun and pnpm. Website packaging
122requires the framework dependencies plus `@alchemy.run/frontend-frameworks` and
123`@vercel/nft`; follow the guide for your [frontend framework](/neon/frontend/vite).
124
125Production artifacts target Linux ARM64/glibc and export a Fetch handler. Native
126addons built for macOS or a different Node ABI are not deployable substitutes.
127Local framework development is useful but does not prove the production artifact
128runs on Neon. Verify the deployed URL, including an update, before routing users
129to it.
130
131## Preserve state before the first deploy
132
133Record your stack, stage, profile, and state-store location. The tutorial uses
134local `.alchemy` state; other stacks can use a configured remote state store.
135Keep recoverable, access-controlled backups. `Redacted` values still need to be
136persisted for recovery and are not an encryption guarantee for the state store.
137See [State and recovery](/neon/guides/state-recovery) before deleting local files
138or replacing a deployment machine.
139
140## Next steps
141
142- [Neon overview](/neon) — resources and runtime bindings.
143- [Upload tutorial](/neon/tutorial) — deploy an authenticated application.
144- [Organization governance](/neon/governance) — manage existing administrative controls.