Setup

Prerequisites

• Bun (recommended) or Node.js 22+
• An AWS account and an IAM identity with permission to create the resources you plan to deploy

Create a project

bun

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

npm

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

pnpm

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

yarn

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

Install

bun

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

npm

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

pnpm

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

yarn

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

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 two 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. When the SSO session expires, run alchemy profile edit --reconfigure AWS 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 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.