localstack¶
LocalStack 4 — S3, SQS, SNS, Lambda, DynamoDB, Kinesis, IAM and the rest, answering on your machine so tests and local runs never touch a real AWS account.
spin up localstack # http://localhost:4566
spin cli localstack -- s3 mb s3://demo # awslocal, inside the container
spin cli localstack -- s3 ls
curl localhost:4566/_localstack/health # what is available
Ports¶
| Service | Host port | Container | Env var |
|---|---|---|---|
| Gateway | 4566 |
4566 | LOCALSTACK_PORT |
Every service is behind that one port — it is the endpoint URL you point an SDK at, not one port per service.
Credentials¶
AWS SDKs refuse to sign a request without credentials, and LocalStack does not check them. The convention is:
AWS_ACCESS_KEY_ID=test
AWS_SECRET_ACCESS_KEY=test
AWS_DEFAULT_REGION=us-east-1
AWS_ENDPOINT_URL=http://localhost:4566
Recent SDKs and the AWS CLI v2 read AWS_ENDPOINT_URL, so those four
variables are usually the whole of the setup. Older ones need the endpoint
passed per call (aws --endpoint-url=http://localhost:4566 s3 ls).
Using it¶
awslocal is the AWS CLI with the endpoint already set, and it ships in the
image:
spin cli localstack -- s3 mb s3://demo
spin cli localstack -- sqs create-queue --queue-name jobs
spin cli localstack -- dynamodb list-tables
From your own shell, with the variables above exported, the plain aws CLI
and any SDK work the same way.
Storage¶
localstack-data holds the working state and the caches LocalStack builds.
Note that it is not a save file: in the community edition the resources you
create are gone when the container stops. Persistence across restarts is a Pro
feature (PERSISTENCE=1), so treat every spin up localstack as an empty
account and create what a test needs in the test.
Notes¶
- The image is pinned to
4, notlatest. LocalStack's CalVer tags (latest,stable,2026.x) are the Pro image: without a validLOCALSTACK_AUTH_TOKENthey print a licence error and quit with exit 55.4is the last freely usable line. - The Docker socket is mounted because LocalStack runs each Lambda invocation
in a container of its own. Without it every service works except Lambda. It
is also root on the host by another name — run this locally, not on
anything exposed. On Windows the host side is
//./pipe/docker_engine; seeLOCALSTACK_DOCKER_SOCK. - No GUI, so
spin open localstackhas nothing to open. LocalStack's web interface is a hosted service at app.localstack.cloud that needs an account;/_localstack/healthis the local equivalent and answers with JSON. - Only the gateway port is published. LocalStack can also allocate per-service
ports in
4510-4559; publishing fifty ports for a case most setups never hit is not worth it, and anything that needs one can add it tocompose.yaml.