clover's git

the-knife

1	---
2	title: Setup
3	description: Connect Alchemy to AWS with SSO, stored access keys, or CI environment credentials.
4	---
5
6	import { Code, Tabs, TabItem } from "@astrojs/starlight/components";
7	import { effectVersion } from "../../../versions";
8
9	export const pkgs = `"alchemy@latest" "effect@${effectVersion}" "@effect/platform-bun@${effectVersion}" "@effect/platform-node@${effectVersion}"`;
10
11	## Prerequisites
12
13	- [Bun](https://bun.sh) or Node.js 22+
14	- An AWS account and an IAM identity with permission to create
15	the resources you plan to deploy
16
17	## Create a project
18
19	<Tabs syncKey="pkgManager">
20	<TabItem label="bun" icon="bun">
21	<Code code="mkdir my-app && cd my-app && bun init -y" lang="sh" />
22	</TabItem>
23	<TabItem label="npm" icon="npm">
24	<Code code="mkdir my-app && cd my-app && npm init -y" lang="sh" />
25	</TabItem>
26	<TabItem label="pnpm" icon="pnpm">
27	<Code code="mkdir my-app && cd my-app && pnpm init" lang="sh" />
28	</TabItem>
29	<TabItem label="yarn" icon="seti:yarn">
30	<Code code="mkdir my-app && cd my-app && yarn init -y" lang="sh" />
31	</TabItem>
32	</Tabs>
33
34	## Install
35
36	<Tabs syncKey="pkgManager">
37	<TabItem label="bun" icon="bun">
38	<Code code={`bun add ${pkgs}`} lang="sh" />
39	</TabItem>
40	<TabItem label="npm" icon="npm">
41	<Code code={`npm install ${pkgs}`} lang="sh" />
42	</TabItem>
43	<TabItem label="pnpm" icon="pnpm">
44	<Code code={`pnpm add ${pkgs}`} lang="sh" />
45	</TabItem>
46	<TabItem label="yarn" icon="seti:yarn">
47	<Code code={`yarn add ${pkgs}`} lang="sh" />
48	</TabItem>
49	</Tabs>
50
51	## How Alchemy gets AWS credentials
52
53	Connect AWS with `alchemy profile edit --add AWS` and pick an
54	authentication method. The choice is saved to your **`default`**
55	[profile](/environments/profiles) and reused on every subsequent
56	command; a deploy with nothing configured fails with that exact
57	command to run. Authentication changes only through the `profile` command.
58
59	There are two local profile methods:
60
61	### SSO (recommended)
62
63	Alchemy runs `aws sso login --profile <name>` for you and loads
64	credentials from the AWS SSO cache. You pick which profile from
65	`~/.aws/config` to use; the account ID and region come from that
66	profile. When the SSO session expires, run
67	`alchemy profile edit --reconfigure AWS` to refresh it.
68
69	### Stored access keys
70
71	Paste an access key ID, secret access key, optional session
72	token, and region into the interactive prompt. Alchemy verifies
73	them against STS and saves them under
74	`~/.alchemy/credentials/<profile>/` for future runs.
75
76	### CI environment credentials
77
78	When `CI=true`, Alchemy bypasses profiles and reads the standard AWS
79	variables directly:
80
81	```sh
82	export AWS_ACCESS_KEY_ID=...
83	export AWS_SECRET_ACCESS_KEY=...
84	export AWS_SESSION_TOKEN=... # optional
85	export AWS_REGION=us-east-1 # or AWS_DEFAULT_REGION
86	```
87
88	The region is required. The account ID is taken from
89	`AWS_ACCOUNT_ID` if set, otherwise resolved once via STS
90	`GetCallerIdentity`. No profile is created or persisted in CI.
91
92	## Managing credentials
93
94	Re-run the setup at any time (e.g. to switch from stored keys to
95	SSO, or to configure a separate `prod` profile):
96
97	```sh
98	alchemy profile edit --reconfigure AWS
99	alchemy profile create prod
100	alchemy profile edit --profile prod --add AWS
101	```
102
103	Inspect what's stored (secrets are redacted):
104
105	```sh
106	alchemy profile show
107	```
108
109	See [Profiles](/environments/profiles) for switching between
110	profiles with `--profile` or `$ALCHEMY_PROFILE`.
111
112	## State storage
113
114	For AWS stacks, pass `AWS.state()` as the Stack's `state`
115	option. Deploy state is stored in an account-regional S3 bucket
116	(`alchemy-state-{accountId}-{region}-an`), created lazily on the
117	first deploy — the same configuration works locally and in CI
118	with no extra setup. For purely local iteration,
119	`Alchemy.localState()` writes state under `.alchemy/` next to
120	your code instead.
121
122	## Next steps
123
124	- [AWS overview](/aws) — pick a runtime and resources.
125	- [Lambda](/aws/compute/lambda) — deploy your first function with a
126	public URL.
127	- [Secrets & env](/aws/security/secrets-env) — profile credentials
128	deploy the stack; app secrets are bindings on the function.