The best way to control Claude Code, Codex and more from any computer or phone

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