Run your AWS CDK applications locally with ldk dev.
Interact with local services using lws.
No credentials. No cost. No waiting.
uvx --from local-web-services ldk dev
Local Web Services is an open-source tool that reads your AWS CDK cloud assembly and recreates your entire application locally. Two complementary CLI tools work together: ldk runs your infrastructure, and lws lets you interact with it.
The development server. Parses your CDK application and spins up local providers for every AWS service you use — DynamoDB, Lambda, S3, SQS, and more. Your entire stack runs locally.
AWS CLI for local services. Interact with your running local stack using familiar AWS SDK commands. Inspect tables, send messages, upload objects — all without touching AWS.
No AWS resources consumed during development. Your entire stack runs on your laptop.
No AWS access keys required. No risk of credential leaks or accidental production changes.
Standard AWS SDK calls work transparently. Your code runs identically locally and in production.
Change your Lambda handlers and see the results instantly. File watchers detect changes and reload automatically — no restart needed.
Real-time web UI showing all resources, API routes, logs, and system status. Browse to http://localhost:3000/_ldk/gui to see everything at a glance.
All Lambda invocations, API requests, and service calls logged in real-time. Stream logs directly in your terminal or via WebSocket to the dashboard.
Building with AWS CDK traditionally means deploying to the cloud just to test your code. Every change triggers a deploy-wait-test cycle that kills your flow and racks up costs.
cdk deploy — wait minutesuvx --from local-web-services ldk dev — ready in secondsPost-deployment testing is slow and expensive. Local Web Services moves testing into the inner loop — before deployment — enabling rapid iteration for developers and AI agents alike.
Edit your code and see the results immediately. Hot reloading picks up changes automatically — no restart, no redeploy, no waiting. The fastest feedback loop for cloud-native development.
AI code editors need fast feedback loops to verify changes. Local Web Services eliminates deployment wait time, enabling AI agents to iterate and validate rapidly without AWS costs.
Your local environment mirrors your AWS architecture. The same services, the same APIs, the same integration patterns — so local testing actually predicts production behavior.
Develop on a plane, in a coffee shop, or in a locked-down network. No AWS account needed, no credentials to manage, no risk of accidental production changes.
Built-in web dashboard and structured logging show all invocations, events, and state changes. Debug with full transparency in real-time instead of hunting through CloudWatch.
Run your full integration test suite in CI without provisioning real AWS resources. Fast, cheap, and reliable automated testing for your cloud-native apps.
Local Web Services parses the output of cdk synth, builds a dependency graph of your infrastructure, and starts local providers for each AWS service — in the right order.
The ldk tool reads your cdk.out/ cloud assembly — the CloudFormation templates, construct tree, and asset paths that cdk synth produces.
It builds a directed graph of your resources and their relationships: which Lambda is triggered by which API route, which function writes to which table, and what depends on what.
Local providers spin up in topological order — tables and queues first, then compute, then API gateways. Each service gets its own HTTP endpoint that speaks the AWS API.
The local runtime sets AWS_ENDPOINT_URL_* environment variables so the standard AWS SDK in your Lambda handlers automatically talks to the local services. No code changes needed.
Get Local Web Services running with the sample project in under five minutes.
npm install -g aws-cdk)git clone https://github.com/local-web-services/sample-project.git
cd sample-project
npm installcdk synthuvx --from local-web-services ldk devThe 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, and an API Gateway — 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.
# 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-documentsThe 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.
Each service has two dimensions of support: CDK constructs parsed from your cdk synth output, and API operations emulated at runtime.
tableName, partitionKey, sortKey, globalSecondaryIndexes
Backed by SQLite. Supports expression attribute names/values, filter expressions, and eventual consistency simulation.
queueName, fifo, visibilityTimeout, contentBasedDeduplication, deadLetterQueue
Supports message attributes, long polling, and dead-letter queue wiring from RedrivePolicy.
bucketName
Backed by the local filesystem. Supports event notifications (ObjectCreated, ObjectRemoved), presigned URL generation, ETags, and content-type headers.
topicName. aws_sns.Subscription is not parsed — subscriptions are wired at runtime via the API or auto-wired by LDK for Lambda/SQS targets.
Supports Lambda and SQS subscription protocols, message attributes, and fan-out to multiple subscribers.
eventBusName, ruleName, eventBus, eventPattern, schedule, targets
Supports event pattern matching, schedule expressions (rate and cron), Lambda targets, and input transformations.
stateMachineName, definitionBody, stateMachineType
State types: Task, Pass, Choice, Wait, Succeed, Fail, Parallel, Map. Supports JSONPath (InputPath, OutputPath, ResultPath), error handling (Retry, Catch), and Standard & Express workflows.
userPoolName, lambdaTriggers (preAuthentication, postConfirmation), passwordPolicy, userPool
Backed by SQLite. Supports JWT token generation (ID, access, refresh), user attributes, and password hashing.
handler, runtime, code, timeout, memorySize, environment
Runs functions locally using Python or Node.js runtimes. Supports timeout enforcement, realistic context objects, and environment variable injection. Not an AWS API endpoint — functions are invoked by other services (API Gateway, SNS, EventBridge, Step Functions).
routes, methods, integrations
HTTP API (V1 proxy integration) that routes requests to local Lambda functions. Supports path parameters, query parameters, and request/response mapping.
containerDefinitions, taskDefinition
Runs services as local subprocesses. Supports health checking, service discovery, file watching with auto-restart, and port mapping. Supports local command overrides via ldk.local_command metadata.
Complete command reference for both ldk and lws tools.
uvx --from local-web-services ldk dev [OPTIONS]Start the full local environment with hot-reload. Watches your source files and restarts handlers on change.
--port, -p API Gateway listen port (default: 3000)--no-persist Disable data persistence — data is lost when ldk stops--force-synth Force CDK synth even if cdk.out exists--log-level, -l Log level: debug, info, warning, error (default: info)--project-dir, -d Project root directory (default: current directory)uvx --from local-web-services ldk invoke [OPTIONS]Invoke a Lambda function directly with a JSON event payload. Useful for testing handlers in isolation.
--function-name, -f Lambda function name (required)--event, -e Inline JSON event payload--event-file Path to JSON event file--project-dir, -d Project root directory (default: current directory)--port, -p Management API port to connect to running ldk devuvx --from local-web-services ldk reset [OPTIONS]Clear all persisted local state — databases, queues, buckets. Start fresh.
--yes, -y Skip confirmation prompt--project-dir, -d Project root directory (default: current directory)--port, -p Management API port to notify running ldk devAWS CLI-style commands for interacting with your local services. Requires a running ldk dev instance.
Show the status of the running ldk dev instance and all providers.
uvx --from local-web-services lws statusDynamoDB table operations.
uvx --from local-web-services lws dynamodb scan \
--table-name MyTableSQS queue operations.
uvx --from local-web-services lws sqs receive-message \
--queue-name MyQueueS3 bucket operations.
uvx --from local-web-services lws s3api list-objects-v2 \
--bucket my-bucketSNS topic operations.
uvx --from local-web-services lws sns publish \
--topic-name MyTopic \
--message "Hello"EventBridge operations.
uvx --from local-web-services lws events put-events \
--entries '[{...}]'Step Functions operations.
uvx --from local-web-services lws stepfunctions start-execution \
--name MyStateMachine \
--input '{...}'Cognito User Pool operations.
uvx --from local-web-services lws cognito-idp sign-up \
--user-pool-name MyPool \
--username user@example.comAPI Gateway test invocation.
uvx --from local-web-services lws apigateway test-invoke-method \
--resource /orders \
--http-method GET