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

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