import PackageManagers from "../../../components/PackageManagers.astro"; export const pkgs = `alchemy@latest @alchemy.run/aws@latest effect @effect/platform-bun @effect/platform-node`; Prerequisites
- Bun or Node.js 24.11.1+
- An AWS account and an IAM identity with permission to create the resources you plan to deploy
Create a project
Install
How Alchemy gets AWS credentials
Connect AWS with alchemy profile edit --add AWS and pick an
authentication method. The choice is saved to your default
profile and reused on every subsequent
command; a deploy with nothing configured fails with that exact
command to run. Authentication changes only through the profile command.
There are three local profile methods:
SSO (recommended)
Alchemy runs aws sso login --profile <name> for you and loads
credentials from the AWS SSO cache. You pick which profile from
~/.aws/config to use; the account ID and region come from that
profile. Use this when your org signs in through IAM Identity
Center. When the SSO session expires, run
alchemy profile refresh to refresh it.
Console login
Alchemy runs aws login --profile <name> (AWS CLI v2.32+) and
loads credentials from the console-login session that command
writes to ~/.aws/config (login_session). Use this when you
sign into the AWS Management Console as a root user, IAM user,
or through IAM federation — the same identity, without long-lived
access keys. When the session expires, run alchemy profile refresh
to refresh it.
Stored access keys
Paste an access key ID, secret access key, optional session
token, and region into the interactive prompt. Alchemy verifies
them against STS and saves them under
~/.alchemy/credentials/<profile>/ for future runs.
CI environment credentials
When CI=true, Alchemy bypasses profiles and reads the standard AWS
variables directly:
export AWS_ACCESS_KEY_ID=...
export AWS_SECRET_ACCESS_KEY=...
export AWS_SESSION_TOKEN=... # optional
export AWS_REGION=us-east-1 # or AWS_DEFAULT_REGION The region is required. The account ID is taken from
AWS_ACCOUNT_ID if set, otherwise resolved once via STS
GetCallerIdentity. No profile is created or persisted in CI.
Managing credentials
Re-run the setup at any time (e.g. to switch from stored keys to
SSO or console login, or to configure a separate prod profile):
alchemy profile edit --reconfigure AWS
alchemy profile create prod
alchemy profile edit --profile prod --add AWS Inspect what's stored (secrets are redacted):
alchemy profile show See Profiles for switching between
profiles with --profile or $ALCHEMY_PROFILE.
State storage
For AWS stacks, pass AWS.state() as the Stack's state
option. Deploy state is stored in a DynamoDB table
(alchemy-state), created lazily on the first deploy. In CI,
provision it once with alchemy state bootstrap --backend aws.
For purely local iteration, Alchemy.localState() writes state
under .alchemy/ next to your code instead.
State from earlier versions lives in an S3 bucket; move it with
alchemy state migrate. See
Migrating from the S3 store.
Next steps
- AWS overview — pick a runtime and resources.
- Lambda — deploy your first function with a public URL.
- Secrets & env — profile credentials deploy the stack; app secrets are bindings on the function.