Setup

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

pnpm

mkdir my-app && cd my-app && pnpm init

bun

mkdir my-app && cd my-app && bun init -y

npm

mkdir my-app && cd my-app && npm init -y

yarn

mkdir my-app && cd my-app && yarn init -y

Install

pnpm

pnpm add alchemy@latest effect @effect/platform-bun @effect/platform-node

bun

bun add alchemy@latest effect @effect/platform-bun @effect/platform-node

npm

npm install alchemy@latest effect @effect/platform-bun @effect/platform-node

yarn

yarn add alchemy@latest effect @effect/platform-bun @effect/platform-node

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 an account-regional S3 bucket (alchemy-state-{accountId}-{region}-an), created lazily on the first deploy — the same configuration works locally and in CI with no extra setup. For purely local iteration, Alchemy.localState() writes state under .alchemy/ next to your code instead.

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.