Running against LocalStack
Everything in this repo that touches AWS (bb deploy, bb invoke, bb teardown, bb bench, bb demo) can run against LocalStack instead of a real account. You can try the whole deploy and invoke cycle without AWS credentials, without paying anything, and without touching a real account. The Runtime API loop, the handler, and the zip are exactly the same artifacts real AWS gets; only the control plane (lambda create-function, invoke, IAM) is emulated.
Quickstart
bb build # build dist/lambda.zip first
bb localstack:demo # start LocalStack + deploy + invoke, no AWS account
bb localstack:stop # stop + remove the container when done
bb localstack:demo starts a detached localstack/localstack container (lambda-mvp-glj-localstack, edge on http://localhost:4566, host docker socket mounted), waits for the edge to answer, then runs this repo's own deploy and invoke tasks unchanged. bb localstack:status reports whether the container is up and the edge is answering.
LocalStack creates the Lambda function containers through the host's docker daemon (that's why the socket is mounted), so the function executes the real bootstrap from your dist/lambda.zip.
The switch: LAMBDA_ENDPOINT_URL
Until you set LAMBDA_ENDPOINT_URL, nothing changes: unset (or blank) means real AWS. Once set, it does two things to every aws CLI call the scripts make:
--endpoint-url <value>is injected as a global option, and- LocalStack's documented dummy credentials (
test/test, regionus-east-1) are exported, unless you've setAWS_ACCESS_KEY_ID,AWS_SECRET_ACCESS_KEYorAWS_DEFAULT_REGIONyourself, in which case yours win.
The real-AWS credential/region preflight in demo/deploy/invoke/bench is skipped when the endpoint is set, so the LocalStack path needs no aws CLI configuration at all.
You can drive it by hand, without the wrapper tasks:
export LAMBDA_ENDPOINT_URL=http://localhost:4566
export AWS_ACCESS_KEY_ID=test AWS_SECRET_ACCESS_KEY=test AWS_DEFAULT_REGION=us-east-1
aws --endpoint-url $LAMBDA_ENDPOINT_URL lambda list-functions # anything, really
bb script/aws_lifecycle.clj deploy # or bb deploy, same code path
bb script/aws_lifecycle.clj invoke
bb script/aws_lifecycle.clj teardown
(Or start your own LocalStack: docker run -d -p 4566:4566 -v /var/run/docker.sock:/var/run/docker.sock localstack/localstack.)
LocalStack's March 2026 licensing change means localstack/localstack:latest (and anything newer) refuses to start without LOCALSTACK_AUTH_TOKEN, even for community features. This repo therefore pins localstack/localstack:4.13.1, the last tag that runs without an account. If you have a token (the free tier works), export LOCALSTACK_AUTH_TOKEN and optionally LOCALSTACK_IMAGE (e.g. localstack/localstack:latest) and the wrapper tasks will pass both to the container.
What LocalStack is good for here, and what it isn't
Good for:
- End-to-end confidence in the deploy/invoke/teardown lifecycle (packaging,
provided.al2023, handler wiring, response/log plumbing) without an account. - Fast iteration on
aws_lifecycle.cljitself. - CI smoke tests.
Not good for:
- Cold/warm boot numbers.
bb benchruns against LocalStack if the endpoint is set, but LocalStack executes your function in a plain docker container on your machine, without Lambda's Firecracker microVM or its per-tier CPU allocation, and on Apple Silicon possibly under emulation. Its numbers say nothing about Lambda cold starts, so runbb benchagainst a real account for those. - IAM fidelity. LocalStack's IAM is permissive; a trust policy that works here may still be rejected by real AWS.
Requirements
- Docker, running, for both the LocalStack container and the function containers it spawns.
- The
awsCLI on PATH (version 2), as for the real-AWS path.