Getting Started

Get Local Web Services running with a sample project in under five minutes. Choose your IaC tool below.

Prerequisites

These are required for both CDK and HCL workflows.

  • uv — Python package runner
  • Docker — required for Lambda runtime emulation
  • Node.js 18+ — required for CDK projects and Node.js Lambda handlers

CDK Quick Start

Clone a sample CDK project and run it locally in five steps.

Additional Prerequisite

  • AWS CDK CLI (npm install -g aws-cdk)

1. Clone the sample project

git clone https://github.com/local-web-services/local-web-services.git cd local-web-services/sample-project/cdk npm install

2. Synthesize the CDK app

cdk synth

3. Pull Lambda runtime images (one-time)

uvx --from local-web-services ldk setup lambda

This pulls the official AWS Lambda base images from ECR Public, which include the AWS SDK pre-installed. You only need to do this once.

4. Start the local environment

uvx --from local-web-services ldk dev

The ldk dev command reads the cloud assembly and starts local providers for every resource in the stack — DynamoDB tables, SQS queues, S3 buckets, Lambda functions, API Gateway, SSM parameters, and Secrets Manager secrets — all wired together.

Once started, open http://localhost:3000/_ldk/gui to access the web dashboard with real-time logs, resource explorer, and system status.

5. Make requests

# Create an order via API Gateway curl -X POST http://localhost:3000/orders \ -H "Content-Type: application/json" \ -d '{"customerName": "Jane", "items": ["Widget"], "total": 29.99}' # Get the order curl http://localhost:3000/orders/{orderId} # Inspect data with lws uvx --from local-web-services lws dynamodb scan --table-name OrdersTable uvx --from local-web-services lws sqs receive-message --queue-name OrderQueue uvx --from local-web-services lws s3api list-objects-v2 --bucket order-documents

The sample project is an order processing system with API Gateway, Lambda, DynamoDB, SQS, SNS, S3, and Step Functions — all running on your machine. Use lws commands to inspect the data your application creates.

HCL Quick Start

Clone a sample HCL project and run it locally in six steps.

Additional Prerequisite

1. Clone the HCL sample project

git clone https://github.com/local-web-services/local-web-services.git cd local-web-services/sample-project/hcl cd lambda/create-order && npm install && cd ../.. cd lambda/get-order && npm install && cd ../.. cd lambda/process-order && npm install && cd ../.. cd lambda/generate-receipt && npm install && cd ../..

2. Initialize HCL project

tofu init

3. Pull Lambda runtime images (one-time)

uvx --from local-web-services ldk setup lambda

This pulls the official AWS Lambda base images from ECR Public, which include the AWS SDK pre-installed. You only need to do this once.

4. Start the local environment

uvx --from local-web-services ldk dev

The ldk dev command auto-detects your HCL project, starts all AWS service providers in always-on mode, and generates a _lws_override.tf file that redirects Terraform's AWS provider to your local endpoints.

5. Apply HCL

In another terminal, apply your HCL configuration against the local services:

tofu apply -auto-approve

Your HCL tool creates all resources (DynamoDB tables, SQS queues, Lambda functions, API Gateway routes, etc.) against your local endpoints. No AWS account needed.

6. Test the application

# Run the end-to-end test script bash test-orders.sh # Or test manually with lws commands uvx --from local-web-services lws dynamodb scan --table-name Orders uvx --from local-web-services lws stepfunctions start-execution \ --name OrderWorkflow \ --input '{"orderId": "test-123", "items": ["widget"], "total": 29.99}'

Claude Code Integration

Set up slash commands and context for AI code editors so Claude can manage your local AWS fakes and chaos testing.

Initialize

uvx --from local-web-services lws init

This creates three files in your project:

  • CLAUDE.md — LWS quick reference and CLI commands that Claude reads automatically
  • .claude/commands/lws/fake.md — The /lws:fake slash command
  • .claude/commands/lws/chaos.md — The /lws:chaos slash command

The command is idempotent — running it again updates existing files without duplicating content.

Slash Commands

Once initialized, two slash commands are available in Claude Code:

/

/lws:fake

Guides Claude through creating and configuring AWS operation fakes. Supports file-based fakes (persist across restarts) and runtime fakes (configured on the fly). Includes service-aware helpers for DynamoDB JSON, S3 XML, SQS messages, and more.

/

/lws:chaos

Guides Claude through enabling chaos engineering on AWS services. Configure error rates, latency injection, timeouts, and connection resets. Includes common scenarios for testing retry logic, circuit breakers, and timeout handling.

What Gets Added to CLAUDE.md

The CLAUDE.md snippet gives Claude context about your LWS environment, including how to start the dev server, check status, and use fake and chaos commands. This context is read automatically by Claude Code when working in your project.