Wraps deploys infrastructure directly to your AWS account, so it needs valid AWS credentials at both setup time and runtime. This guide covers every method supported.
Prerequisites
- An AWS account (create one free)
- Node.js 20 or later
- Wraps CLI installed or available via
npx @wraps.dev/cli
The AWS Free Tier includes 3,000 SES emails per month for the first 12 months, making it free to get started.
Authentication methods
AWS CLI (recommended)
Environment variables
IAM role
OIDC
The AWS CLI is the simplest way to authenticate for local development. Credentials are stored in ~/.aws/credentials and picked up automatically by the Wraps CLI and SDK.Create an IAM user
- Open the AWS IAM Console
- Click Create user and name it
wraps-cli
- Attach the AdministratorAccess policy (you can restrict permissions later using
wraps permissions)
- On the user page go to Security credentials → Create access key
- Select Command Line Interface (CLI) and copy your Access Key ID and Secret Access Key
Configure the CLI
When prompted:AWS Access Key ID: [paste your access key]
AWS Secret Access Key: [paste your secret key]
Default region: us-east-1
Default output format: [press Enter]
Verify the connection
A passing check confirms that Wraps can connect to your account. Environment variables work well for containerised workloads, Railway, and any platform that doesn’t support IAM roles or OIDC.Set the following variables in your shell or platform dashboard:export AWS_ACCESS_KEY_ID=AKIAIOSFODNN7EXAMPLE
export AWS_SECRET_ACCESS_KEY=wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY
export AWS_REGION=us-east-1
~/.aws/credentials → IAM role.Never commit long-lived credentials to source control. Use your platform’s secret manager or environment variable UI instead.
When your application runs on AWS compute (Lambda, ECS, EC2), attach an IAM role directly to the resource. No credentials need to be stored anywhere.The AWS SDK automatically picks up the role from the instance metadata service. Use the default credential chain in the SDK:import { WrapsEmail } from '@wraps.dev/email';
// Automatically uses the attached IAM role
const email = new WrapsEmail({ region: 'us-east-1' });
wraps permissions --service email
wraps permissions --json # machine-readable output
OIDC lets platforms like Vercel and GitHub Actions assume an AWS IAM role using short-lived tokens — no stored credentials required.
- Vercel — see the Vercel OIDC guide for a full walkthrough
- GitHub Actions — configure
aws-actions/configure-aws-credentials with your role ARN
In the SDK, pass the role ARN:import { WrapsEmail } from '@wraps.dev/email';
const email = new WrapsEmail({
roleArn: process.env.AWS_ROLE_ARN,
});
Interactive setup wizard
If you’re starting from scratch, the setup wizard walks you through every step interactively:
The wizard detects your current state — whether you have the AWS CLI installed, existing credentials, or an expired SSO session — and guides you through the right path.
Flags:
| Flag | Description |
|---|
-y, --yes | Skip confirmation prompts |
Diagnosing issues
Run the doctor command to get a full diagnostic report of your AWS configuration:
The doctor checks:
- AWS CLI installation and version
- Credentials file (
~/.aws/credentials)
- Config file (
~/.aws/config)
- Whether credentials can actually connect to AWS
- The active region
- SES sandbox vs. production access status
- SSO session validity and expiry
Example output:
[✓] AWS CLI v2.15.0 installed
[✓] Credentials file exists (~/.aws/credentials)
[✓] Can connect to AWS (account: 123456789012)
[✓] Region set: us-east-1
[✓] SES has production access
If you see SES is in sandbox mode, you can only send to verified email addresses. Request production access in the AWS SES console to remove the restriction.
Required IAM permissions
To see the exact permissions Wraps needs before deploying:
# All services
wraps permissions
# Email only
wraps permissions --service email
# JSON for policy documents
wraps permissions --json
# For a specific preset
wraps permissions --preset production
AdministratorAccess. 