Skip to content

Setup

Prerequisites

Section titled “Prerequisites”
  • Node.js 24.11.1+ or Bun
  • An AWS account and an IAM identity with permission to create the resources you plan to deploy

Create a project

Section titled “Create a project”
Terminal window
mkdir my-app && cd my-app && pnpm init

Install

Section titled “Install”
Terminal window
pnpm add https://pkg.alchemy.run/alchemy/pr:2930:a10573e https://pkg.alchemy.run/@alchemy.run/aws/pr:2930:a10573e effect @effect/platform-bun @effect/platform-node

How Alchemy gets AWS credentials

Section titled “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. Start with console login unless your organization already signs in through IAM Identity Center.

Section titled “Console login (recommended)”

Console login is AWS’s keyless sign-in for every account. You sign in to the AWS Management Console in your browser, as the root user, an IAM user or through federation, and the AWS CLI receives short-lived credentials for that same identity. There’s nothing to set up in the account, and no long-lived access keys on your machine.

Alchemy runs aws login --profile <name> (AWS CLI v2.32+) for you and loads the session it writes to ~/.aws/config (login_session). When the session expires, run alchemy profile refresh.

SSO through IAM Identity Center

Section titled “SSO through IAM Identity Center”

SSO is for organizations that have set up IAM Identity Center: a single sign-in for many accounts, with users and permission sets managed centrally, often connected to Okta, Google Workspace or Entra ID. It takes setup in an AWS Organization, so it pays off when a team works across several accounts.

Alchemy runs aws sso login --profile <name> for you and loads credentials from the AWS SSO cache. The profile you pick in ~/.aws/config decides the account and region. When the session expires, run alchemy profile refresh.

Stored access keys

Section titled “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

Section titled “CI environment credentials”

When CI=true, Alchemy bypasses profiles and reads the standard AWS variables directly:

Terminal window
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

Section titled “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):

Terminal window
alchemy profile edit --reconfigure AWS
alchemy profile create prod
alchemy profile edit --profile prod --add AWS

Inspect what’s stored (secrets are redacted):

Terminal window
alchemy profile show

See Profiles for switching between profiles with --profile or $ALCHEMY_PROFILE.

State storage

Section titled “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

Section titled “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.