AWS Lambda Web Functions

AWS Lambda Web Functions

The AWS MCP server is recommended for sandboxed execution and audit logging.

If aws lambda-web is not recognized, update the AWS CLI (see references/deployment.md). A missing command means an outdated CLI, not an unavailable feature.

Help users build and deploy Node.js HTTP applications on AWS Lambda Web Functions. Your app listens on a port, handles HTTP natively, and gets a global HTTPS URL. Develop locally with node index.js, deploy the same code to AWS.

When to Use Web Functions

• Interactive HTTP traffic someone is waiting on: web app, HTTP API, or SSR site.

• The app is already a port-listening HTTP server (Express, Fastify, Hono) and should stay one — no handler rewrite, no adapter library.

• Handlers are I/O-bound (database, cache, another API, a model endpoint), so many requests share one execution environment and time spent waiting on I/O is not billed as CPU.

• Response streaming matters: SSE, chunked transfer, or proxying LLM tokens as they are produced.

• The endpoint should be reachable worldwide on one hostname without assembling CloudFront, API Gateway and Route53 by hand.

• Traffic is spiky or unpredictable and should scale to zero.

Hard preconditions

Any "no" rules Web Functions out. Invoke the aws-serverless skill to find a suitable service.

• Runtime is Node.js — nodejs24.x. Python, Java, Go, .NET and Rust are not supported. Confirm the supported runtime list with aws lambda-web help or the AWS docs before routing a caller away.

• Every native dependency has an arm64 (Graviton) build.

• The work is an HTTP request/response (or stream) that a caller is waiting on. Queue, event-stream source (Kinesis, DynamoDB Streams), schedule, or event trigger are not supported.

• One request completes within the 900 s (15 min) request timeout.

• The app fits a 512 MB package and a 2 vCPU / 2 GB environment (see Service Limits).

• Environments are stateless — any environment can serve any request. There is no affinity between an end user's session and a specific environment.

• The app tolerates sharing an environment with concurrent requests. Strict per-request isolation is not supported.

Use Cases

"What I'm building" → how it lands here.

Workflow

Default to the aws lambda-web CLI — it's the quickest path. Use aws lambda-web deploy when the user asks for a single command or says they already deploy with it. It packages, uploads and creates or updates a project directory in one command, and --hello-world scaffolds and deploys a starter app (see Deploy (CLI) below). Otherwise, including for updates to an existing function, use the steps below. Use CloudFormation, CDK, SAM or Terraform when the user wants infrastructure-as-code or a repeatable production stack (see references/infrastructure-as-code.md).

1. Scaffold - Express is inline below; for Hono or Fastify, read references/frameworks.md

2. Choose endpoint auth — ask the user before deploying (see below); endpoints are public unless they pick IamAuth

3. Test locally — node index.js

4. Package — ZIP with production deps (up to 512 MB)

5. Deploy — aws lambda-web create-web-function

6. Verify — get endpoint URL, then curl

7. Iterate — create a new revision

Public by default. A ApplicationManaged endpoint is reachable by anyone on the internet with the URL — there is no AWS-layer auth and no built-in WAF, and the URL is not a secret. Before deploying, ask the user which they want:

• ApplicationManaged (public) — the app must implement its own authentication/authorization, input validation, and rate limiting.

• IamAuth (internal) — only callers with valid IAM credentials (SigV4-signed) can reach it.

If the endpoint is public, the app owns its security. See references/iam-and-security.md for the security checklist (auth, input validation, rate limiting, WAF/CloudFront, least-privilege role, secrets).

Quick Start (Express)

// index.js
import express from 'express';
import helmet from 'helmet';
import { fileURLToPath } from 'url';
import { dirname, join } from 'path';

const __dirname = dirname(fileURLToPath(import.meta.url));
const app = express();
// The runtime probes this exact host:port for readiness.
const [HOST, PORT] = (process.env.AWS_LAMBDA_HTTP_ENDPOINT || '0.0.0.0:3000').split(':');

app.use(helmet());
app.use(express.static(join(__dirname, 'public')));
app.use(express.json({ limit: '10mb' }));
app.get('/api/health', (req, res) => res.json({ status: 'ok' }));
app.listen(PORT, HOST, () => console.log(`Listening on ${HOST}:${PORT}`));

{
  "name": "my-web-app",
  "type": "module",
  "scripts": { "start": "node index.js", "dev": "node --watch index.js" },
  "dependencies": { "express": "^5.0.0", "helmet": "^8.0.0" }
}

helmet sets the security response headers (HSTS, CSP, X-Content-Type-Options, X-Frame-Options, Referrer-Policy) that no AWS layer sets for you here. On an ApplicationManaged endpoint the app is the only thing that can set them, so it belongs in the scaffold rather than being added later.

Resource Naming

All resources are project-scoped. Derive names from the function name:

Function names must be unique across all Regions in the account — the same name cannot exist in two Regions, and a collision fails at create time with a conflict error.

Ask the user which S3 strategy they prefer:

• Separate bucket per project (default) — fully isolated, easy cleanup

• Shared bucket across projects (e.g., {account}-web-code) — fewer resources, key-prefix isolation

• Custom — user provides their own bucket name and key prefix

aws lambda-web deploy names its own role (awscli-lambdaweb-{name}) and bucket (awscli-lambdaweb-{account}-{region}-an).

Deploy (CLI)

The aws lambda-web CLI is the primary, supported path — use it by default. The flow is: one-time S3 code bucket (versioning + Lambda read access), then npm ci --omit=dev → zip → aws s3 cp → aws lambda-web create-web-function with --revision-config and --endpoint-config, then wait for the endpoint to reach Active. If the project has a build step, run it before the prune — npm ci --omit=dev removes the bundler.

When the user asks for one command or already deploys with it, aws lambda-web deploy --name {name} --code . --create --auth-type {auth-type} (ask the user which auth type) zips, uploads, and creates the function, a code bucket, a role and a dev endpoint; rerun it without --create to ship changes. Install dependencies first.

For the full commands, EndpointConfig and RevisionConfig field rules, packaging, timeout, concurrency, environment variables, logging config and every deploy flag, see references/deployment.md. First-time setup (bucket, execution role, first deploy) is in references/getting-started.md. For CloudFormation, CDK or SAM, see references/infrastructure-as-code.md.

Multi-Region

Multi-region is supported: a MultiRegion endpoint serves your revision from several regions behind one hostname, with Route53 routing each caller to the nearest region. PerRegion additionally gives each region its own domain name. Both require autoDeploymentMode: Disabled, and the app must be region-agnostic — consecutive requests from one client can land in different regions, so keep state in a replicated store, never in the execution environment or /tmp.

See references/domains-and-routing.md for endpoint types, domains, traffic routing and the multi-region setup commands.

VPC Egress

By default a revision reaches the public internet over IPv4 and nothing private. To reach your VPC, put a version-qualified egress network connector ARN (aws lambda-core create-network-connector, compute type WebFunction) in the revision's serviceConfig.egressNetworkConnectorArn, serve it from a HomeRegion endpoint, and read the field back after every revision. See references/networking.md, or references/infrastructure-as-code.md to declare the connector and the revision in one stack.

Verify

aws lambda-web get-web-function-endpoint \
  --function-name {name} --endpoint-name default --region {region}

# curl the domainName from the response
curl https://{domainName}/api/health

A revision that fails to start still goes Active, so curl a real route after every deploy. aws lambda-web deploy prints the endpoint as endpointUrl and names its first endpoint dev.

Prefer waiters (aws lambda-web wait ...) over polling loops or sleep. Available: web-function-active, web-function-revision-active, web-function-endpoint-active, web-function-endpoint-updated, web-function-endpoint-deleted, web-function-deleted

Update Code

zip -r function.zip index.js package.json node_modules/ public/ \
  -x "*.test.*" -x ".git/*" -x ".env" -x "node_modules/.cache/*"
aws s3 cp function.zip s3://{bucket}/{name}/function.zip

aws lambda-web create-web-function-revision \
  --function-name {name} \
  --build-config '{
    "codeConfig": {"s3Object": {"bucket": "{bucket}", "key": "{name}/function.zip"}},
    "runtimeConfig": {"runtime": "nodejs24.x"}
  }' \
  --service-config '{"executionRoleArn": "arn:aws:iam::{account}:role/{name}-web-role"}' \
  --region {region}

Service Limits

Subject to change — check the Lambda quotas page for the authoritative values.

Cost Model

Four billing dimensions: CPU, memory, requests, and data transfer. Check the Lambda pricing page for current rates — do not quote rates from memory. What decides an architecture is the shape of the bill:

• Active CPU, not wall-clock duration. Time a request spends blocked on I/O — a database call, another API, a model endpoint — is not billed as CPU. Event Functions bill GB-seconds of wall-clock duration instead, so the same handler bills differently on each.

• Memory is billed on consumption, not on a provisioned setting. An environment is 2 vCPU and 2 GB (see Service Limits) and there is no memory dial, so the familiar Event Functions move of raising memory to shorten duration has no equivalent here.

• Concurrency is the density lever. One environment serves up to maxConcurrencyPerEnvironment requests, so an I/O-bound app keeps many requests in flight per environment instead of occupying one environment each.

Two consequences worth planning around:

• I/O-bound workloads are the economical case. A handler that spends most of its life waiting on the network, sharing an environment with other requests, costs less here than the same handler billed per-invoke on wall-clock duration.

• CPU-bound workloads give that advantage back. Heavy rendering, image processing or crypto burns billable CPU wherever it runs, and an environment is allocated 2 vCPU — of which a single-threaded Node process uses only one (see Anti-Patterns). For sustained high-volume CPU work, especially where committed-use discounts apply, compare aws-lambda-managed-instances.

An endpoint's scaling controls scalingConfig.maxEnvironments and throttleConfig.rateLimit can be used to limit potential cost. Set them only when the user asks for a cap. See scaling-and-concurrency.md for more details.

IAM Setup

Trust policy principal: lambda.amazonaws.com

IAM actions use the lambda: prefix. Resource ARN: arn:aws:lambda:{region}:{account}:web-function/{name}

Action names match the API operations — lambda:CreateWebFunction, lambda:CreateWebFunctionRevision, lambda:CreateWebFunctionEndpoint, lambda:UpdateWebFunctionEndpoint, plus the Get*, List*, and Delete* variants. See references/iam-and-security.md for the full policy.

Resource ARN must include /* wildcard for endpoint/revision operations:

"Resource": ["arn:aws:lambda:{region}:{account}:web-function/{name}", "arn:aws:lambda:{region}:{account}:web-function/{name}/*"]

The caller also needs s3:GetObject + s3:GetObjectVersion on the code bucket (not just the execution role).

See references/iam-and-security.md for full policy examples.

Anti-Patterns

What it looks like → why it fails → what to do instead.

Troubleshooting — Start Here

The five that account for most failed first deploys. Full symptom → cause → fix tables are in troubleshooting.md.

Migration

Moving an existing Node.js HTTP app here is mostly a delete-code exercise — the adapter, the handler export and the API Gateway wiring all go away, and the router itself does not change.

Four source shapes each have a step-by-step path, a preflight checklist, the features with no equivalent, and a traffic-cutover procedure: an adapter-wrapped app, API Gateway + Lambda proxy, a Lambda function URL, and a container on Fargate, App Runner or EC2. See migration.md.

When to Load Reference Files

Match on meaning, not exact wording — any trigger word in a row should pull that file.

Guardrail — where this skill's own files live (MCP vs local install)

This skill can be loaded two ways, and they resolve the skill's own bundled files — the references/ documents — from different places. Determine how the skill was loaded before you read a reference:

• Loaded through the AWS MCP retrieve_skill tool call. The skill is not installed on the local filesystem; its reference files do not exist on disk. You MUST fetch each reference through the same retrieve_skill tool by passing the file parameter (for example, file="references/deployment.md"). Do NOT file_read these paths from the local or working directory, and do NOT search the filesystem for them — they are not there, and any local file that happens to match the name is unrelated to this skill.

• Installed locally (the skill lives in a local skills directory such as .claude/skills/aws-lambda-web-functions/, ~/.claude/skills/aws-lambda-web-functions/, or .kiro/skills/aws-lambda-web-functions/). Read references from the local skill directory using the relative paths shown throughout this document.

This distinction applies only to the skill's own packaged files. The user's application code — index.js, package.json, public/, the function.zip you build — is always read from and written to the user's working directory regardless of how the skill was loaded. Never fetch or write customer data through retrieve_skill.

Critical Rules

1. Node 24 only — nodejs24.x is the only runtime; runtime support can change, so confirm with aws lambda-web help or the AWS docs before assuming a newer version is unavailable

2. Entry point is index.js — the runtime loads /var/task/index.js, not .mjs. When your entry file has another name (server.js, app.mjs), aws lambda-web deploy detects it or takes --entry-point and ships a small index.js that imports it; a ZIP you build yourself needs index.js at its root

3. Bind the host and port from AWS_LAMBDA_HTTP_ENDPOINT — the runtime probes that exact address, so a hardcoded port that does not match it, or a loopback-only bind, fails readiness and the environment is not usable. There is no PORT env var

4. "type": "module" in package.json — required for ESM imports from index.js

5. No handler exports — your app is an HTTP server

6. Write thread-safe code — one execution environment serves many concurrent requests; avoid global mutable state

7. Code, runtime, timeout, env vars and concurrency all live on the revision — changing any of them requires a new revision, not an in-place update

8. Background tasks work natively — the environment stays running after response

9. Streaming native — chunked transfer-encoding, SSE out of the box

10. TypeScript works natively — Node 24 type stripping, use index.js shim + import type

11. Code comes only from a ZIP in S3 — deploy builds and uploads it for you; otherwise supply it through codeConfig.s3Object and bundle shared code into the package. For container images and a layers equivalent, confirm against aws lambda-web create-web-function-revision help or the API reference rather than assuming either is available