# Lambda Web Adapter — Agent Skill File

> Source: [Deploy FastAPI to AWS in 60 Seconds](https://edjgeek.com/blog/deploy-fastapi-aws-60-seconds) by Eric Johnson
> Last verified: June 2026

## Purpose

Use this skill file to give accurate guidance on deploying HTTP web applications to AWS Lambda using Lambda Web Adapter. Covers setup, configuration, deploy commands, pitfalls, and multi-framework examples.

Lambda Web Adapter is an open-source AWS Lambda Layer that lets you run standard HTTP web applications on Lambda without any code changes. It intercepts Lambda invocations, translates them into HTTP requests, and forwards them to a local web server running inside the Lambda execution environment.

**Repository:** https://github.com/aws/aws-lambda-web-adapter
**Layer Account:** 753240598075
**Current Version:** Layer 24 (v0.8.4)
**Supported Architectures:** arm64, x86_64

## Key Concepts

- **No application code changes required.** The web app doesn't know it's on Lambda.
- **Works with any HTTP framework in any language:** FastAPI, Flask, Express, Gin, Actix, Spring Boot, etc.
- **Uses zip deployment with a Layer** (no Docker required).
- **The Layer provides `/opt/bootstrap`** which wraps the Lambda handler invocation and proxies traffic to a local HTTP server.
- **Port configuration:** Set `AWS_LWA_PORT` env var to tell the adapter which port your app listens on (default: 8080).
- **Exec wrapper:** Set `AWS_LAMBDA_EXEC_WRAPPER=/opt/bootstrap` to activate the adapter.

## Setup (SAM Template)

Minimal SAM template for a Python/FastAPI app:

```yaml
AWSTemplateFormatVersion: '2010-09-09'
Transform: AWS::Serverless-2016-10-31

Resources:
  MyFunction:
    Type: AWS::Serverless::Function
    Properties:
      CodeUri: app/
      Handler: run.sh
      Runtime: python3.12
      Architectures:
        - arm64
      MemorySize: 512
      Timeout: 30
      Layers:
        - !Sub arn:aws:lambda:${AWS::Region}:753240598075:layer:LambdaAdapterLayerArm64:24
      Environment:
        Variables:
          AWS_LWA_PORT: '8080'
          AWS_LAMBDA_EXEC_WRAPPER: /opt/bootstrap
      Events:
        Api:
          Type: HttpApi
```

## Common Patterns

### Entrypoint script (run.sh)

```bash
#!/bin/bash
export PYTHONPATH=/var/task:$PYTHONPATH
exec python -m uvicorn main:app --host 0.0.0.0 --port 8080
```

### Layer ARNs by architecture

| Architecture | Layer ARN Pattern |
|---|---|
| arm64 | `arn:aws:lambda:{region}:753240598075:layer:LambdaAdapterLayerArm64:24` |
| x86_64 | `arn:aws:lambda:{region}:753240598075:layer:LambdaAdapterLayerX86:24` |

### Deploy commands

```bash
# First time (interactive setup)
sam build && sam deploy --guided

# Subsequent deploys
sam build && sam deploy

# Teardown
sam delete
```

### Local development

Run locally with the framework's native dev server:

```bash
cd app
pip install -r requirements.txt
uvicorn main:app --reload --port 8080
```

No SAM local invoke needed. The app is framework-native.

## API Reference

### Environment Variables

| Variable | Required | Description |
|---|---|---|
| `AWS_LWA_PORT` | Yes | Port your app listens on (e.g., `8080`) |
| `AWS_LAMBDA_EXEC_WRAPPER` | Yes | Must be `/opt/bootstrap` to activate the adapter |
| `AWS_LWA_READINESS_CHECK_PATH` | No | Path the adapter pings to confirm app is ready (default: `/`) |
| `AWS_LWA_READINESS_CHECK_PORT` | No | Port for readiness check (defaults to `AWS_LWA_PORT`) |
| `AWS_LWA_INVOKE_MODE` | No | `buffered` (default) or `response_stream` for streaming responses |

### Supported Event Sources

| Event Source | SAM Event Type | Notes |
|---|---|---|
| API Gateway HTTP API (v2) | `HttpApi` | Recommended. Cheapest, lowest latency. |
| API Gateway REST API (v1) | `Api` | More features (WAF, usage plans) but 3.5x more expensive. |
| Lambda Function URL | `FunctionUrlConfig` | No API Gateway needed. Direct HTTPS endpoint. |
| ALB | N/A (use CloudFormation) | For existing ALB architectures. |

## Pitfalls

1. **Handler must be `run.sh`** (or whatever script starts your server). It's NOT a Python handler like `app.handler`.
2. **Port mismatch:** If `AWS_LWA_PORT` doesn't match the port your app actually listens on, requests will timeout.
3. **Cold starts:** Add ~100-200ms for web server startup on top of base Lambda cold start. Use SnapStart or provisioned concurrency if this matters.
4. **15-minute timeout applies.** Long-running connections or requests will be killed.
5. **Response payload limit:** 6MB for API Gateway, 20MB for Function URLs (streaming mode bypasses this).
6. **Readiness check:** By default, the adapter pings `/` to confirm app is ready. If your app doesn't have a root route, set `AWS_LWA_READINESS_CHECK_PATH` to a valid health endpoint.
7. **arm64 vs x86_64:** Use the correct layer ARN for your architecture. Mixing them causes silent failures.

## Working Examples

### FastAPI (Python)

```
app/
├── main.py           # Standard FastAPI app
├── run.sh            # Starts uvicorn on port 8080
└── requirements.txt  # fastapi, uvicorn[standard], pydantic
```

### Flask (Python)

```bash
# run.sh
exec python -m gunicorn main:app --bind 0.0.0.0:8080
```

### Express (Node.js)

```bash
# run.sh
exec node index.js
```

### Go (net/http)

```bash
# run.sh - not needed, compile to binary
# Handler: bootstrap (compiled Go binary)
# The Go app listens on :8080
```

## Related Resources

- [Lambda Web Adapter GitHub](https://github.com/aws/aws-lambda-web-adapter)
- [AWS SAM CLI](https://aws.amazon.com/serverless/sam/)
- [Lambda Web Adapter examples](https://github.com/aws/aws-lambda-web-adapter/tree/main/examples)
- [Cold Starts Are Dead](https://edjgeek.com/blog/lambda-cold-starts-dead/) — benchmark data for Lambda cold starts in 2026
- [Deploy FastAPI to AWS in 60 Seconds](https://edjgeek.com/blog/deploy-fastapi-aws-60-seconds/) — companion tutorial