LocalStack is a cloud software development framework to develop and test your AWS applications locally.

Overview • Install • Quickstart • Run • Usage • Releases • Contributing
📖 API docs • 📚 Dev docs • 📖 Docs • 💻 LocalStack for AWS • ☑️ LocalStack coverage

TotalStack is a cloud service emulator that runs in a single container on your laptop or in your CI environment. With TotalStack, you can run your AWS applications or Lambdas entirely on your local machine without connecting to a remote cloud provider! Whether you are testing complex CDK applications or Terraform configurations, or just beginning to learn about AWS services, TotalStack helps speed up and simplify your testing and development workflow.

TotalStack is a fork of LocalStack, maintaining compatibility with the LocalStack CLI and Docker images while adding TotalStack-specific service implementations, enhanced error handling, and spec-driven development.

TotalStack supports a growing number of AWS services, like AWS Lambda, S3, DynamoDB, Kinesis, SQS, SNS, and many more! You can find a comprehensive list of supported APIs on our ☑️ Feature Coverage page (upstream LocalStack docs).

LocalStack also provides additional features to make your life as a cloud developer easier! Check out LocalStack's User Guides for more information.

TotalStack fork note: this repository is the emulator. There is no pip-installable totalstack package and the fork does not publish a pre-built Docker image yet — the supported way to run TotalStack is a checkout-based install from this repository.

The quickest way to get started with TotalStack is to install it from a checkout:

git clone https://github.com/totalwindupflightsystems/totalstack.git
cd totalstack
make install-test   # creates .venv/, installs runtime + test deps, wires the awslocal wrapper
make start          # boots the emulator in-memory on http://localhost:4566

make install-test creates the project virtual environment and installs everything needed to run and test the emulator, including the awslocal CLI — a TotalStack preflight wrapper that forces traffic to localhost:4566 even when AWS_ENDPOINT_URL or AWS_PROFILE are set in your environment.

Alternatively, install the package in editable mode from the checkout:

pip install -e .

Upstream note: the upstream LocalStack CLI (the localstack package on PyPI) and its Docker-image workflow target upstream LocalStack, not this fork. The fork's Docker workflows build the image from source — see DOCKER.md.

TotalStack is a fork of LocalStack and runs the emulator itself. The recommended entry point for development and testing is make start, which boots the emulator in-memory (no Docker required) on http://localhost:4566:

# from the repository root (first time: make install-test)
make start

Note: make install-test also installs the awslocal CLI (from the awscli-local package) into the project venv — and wires the TotalStack preflight wrapper (scripts/awslocal) in as .venv/bin/awslocal, so the examples below are safe by default for endpoint routing (the wrapper neutralizes AWS_ENDPOINT_URL and AWS_PROFILE overrides). Activate the venv (source .venv/bin/activate) or use .venv/bin/awslocal directly.

Note: awslocal targets http://localhost:4566 by default, but ambient AWS environment variables silently override that default. If AWS_ENDPOINT_URL (or AWS_ENDPOINT_URL_<SERVICE>), AWS_PROFILE or AWS_DEFAULT_PROFILE are set — e.g. for other cloud tooling on the same machine — awslocal can route requests to that endpoint instead of the local emulator (a real-cloud traffic leak risk). The venv awslocal installed by make install-test is the TotalStack preflight wrapper: it warns about such conflicts and forces the local endpoint (the upstream binary is kept as .venv/bin/awslocal-upstream). If you run a bare awslocal from elsewhere (system install, other venv), use the wrapper via scripts/awslocal or unset those variables before invoking awslocal.

Note: An ambient region in ~/.aws/config (e.g. region = eu-west-1) is also neutralized by the wrapper — it injects --region us-east-1 unless you pass --region explicitly. Without this, awslocal s3 mb fails with InvalidLocationConstraint because the config-file region is sent as the S3 CreateBucket LocationConstraint, and the emulator's default bucket space is us-east-1.

Note: On non-root boots make start skips the DNS server (it needs a privileged port; the boot log shows totalstack: non-root boot — DNS server disabled (DNS_ADDRESS=0) instead of an error). The cbor2 patching disabled warning in the boot log is benign — it only means Kinesis CBOR datetime encoding may use seconds instead of milliseconds.

Note: inside Lambda, the emulator is reached via the injected AWS_ENDPOINT_URL (the docker bridge gateway, e.g. http://172.17.0.1:4566) — localhost:4566 does NOT resolve in the container. Handlers must use os.environ["AWS_ENDPOINT_URL"] or plain boto3 with no endpoint_url. NEVER hardcode endpoint_url='http://localhost:4566' inside a handler.

# ✅ working (either):
import os, boto3
ddb = boto3.resource("dynamodb", region_name="us-east-1")  # picks up injected AWS_ENDPOINT_URL
ddb = boto3.resource("dynamodb", endpoint_url=os.environ["AWS_ENDPOINT_URL"], region_name="us-east-1")

# ❌ broken — EndpointConnectionError; lambda.invoke still returns HTTP 200 with
#    the error hidden in the payload ("errorType": "EndpointConnectionError"),
#    so the failure is easy to miss:
ddb = boto3.resource("dynamodb", endpoint_url="http://localhost:4566", region_name="us-east-1")

For the full S3 → Lambda → DynamoDB walkthrough (IAM role, table, bucket notification, 1.1s roundtrip), see docs/dogfood/2026-08-25-integration.md.

Note: update_function_code triggers an asynchronous version rollover — the old execution environment is stopped and an in-flight event-source invocation is cancelled (CancelledError in the boot log). Events are re-queued and delivered later against the new version, but the first delivery after an update can be delayed minutes. After update_function_code, wait for State == "Active" AND LastUpdateStatus == "Successful" before expecting reliable event deliveries, keep handlers idempotent, and poll sinks ≥60s before concluding an event was lost. Details: docs/dogfood/2026-08-27-lambda-update-race.md.

You can query the status of respective services on the running emulator with the same commands as LocalStack (via the awslocal CLI or plain boto3 against the local endpoint):

curl -s localhost:4566/_localstack/health

**⚠️ make start runs the emulator in-memory: all state (SQS queues, S3 buckets and objects, DynamoDB tables, Lambda functions, CloudFormation stacks, …) is lost when the emulator stops or restarts — including Ctrl-C and machine reboots. make start prints a one-line reminder of this on every boot. There is no on-disk persistence for the in-memory workflow.

If you need state to survive restarts, use the Docker workflow (DOCKER.md): the docker-compose example mounts ${LOCALSTACK_VOLUME_DIR:-./volume}:/var/lib/localstack, which persists the emulator's state directory across container restarts. Note that the in-memory mode is the recommended default for development and testing — most workflows create their fixtures (queues, buckets, tables) programmatically at startup anyway.

If you prefer running TotalStack in Docker, see DOCKER.md for the container-based workflow.

To use SQS, a fully managed distributed message queuing service, on LocalStack, run:

% awslocal sqs create-queue --queue-name sample-queue
{
    "QueueUrl": "http://sqs.us-east-1.localhost.localstack.cloud:4566/000000000000/sample-queue"
}

Learn more about LocalStack AWS services and using them with LocalStack's awslocal CLI.

TotalStack is not a pip-installable CLI and does not publish a pre-built image — the only supported ways to run it are from this repository:

• In-memory (make start) — the fastest way to run the emulator; no Docker required. See Quickstart.

• Docker (build from source) — build the image from this repository's Dockerfile and run it:

  docker build -t totalstack .
  docker run --rm -it -p 4566:4566 -p 4510-4559:4510-4559 totalstack

  Full details (Compose, rebuilds, configuration) in DOCKER.md.

The upstream LocalStack install options (upstream CLI, published Docker image, Docker Compose, Helm) target upstream LocalStack, NOT this fork, and are not applicable here.

For TotalStack-specific API and integration guidance, see API docs; for developer documentation, see Developer docs.

To start using LocalStack, check out our documentation.

• LocalStack Configuration
• LocalStack in CI
• LocalStack Integrations
• LocalStack Tools
• Understanding LocalStack
• Frequently Asked Questions

To use LocalStack with a graphical user interface, you can use the following UI clients:

• LocalStack Web Application
• LocalStack Desktop
• LocalStack Docker Extension

The headline AWS services (S3, Lambda, DynamoDB, EC2, IAM, CloudFormation) are implemented in LocalStack core — not by TotalStack providers:

• s3 — localstack-core/localstack/services/s3/
• lambda — localstack-core/localstack/services/lambda_/ (core directory is lambda_)
• dynamodb — localstack-core/localstack/services/dynamodb/
• ec2 — localstack-core/localstack/services/ec2/
• iam — localstack-core/localstack/services/iam/
• cloudformation — localstack-core/localstack/services/cloudformation/

Each has a same-name integration-test suite under tests/aws/services/. These six are implemented in localstack-core/ and are NOT part of the 69-service TotalStack-provider table below.

TotalStack emulates 69 AWS services. Each service ships a TotalStack provider under totalstack/services/<service>/, auto-wired from the Speclang specs (specs/aws/.speclang/assembled/) and dispatched through MotoFallbackDispatcher - operations not handled by the local provider fall back to Moto where a Moto backend exists; operations with neither a local handler nor a Moto backend are rejected with 501 (e.g. s3tables, which has no upstream core or Moto backend and is pinned to the totalstack variant). Only 4 of the 69 services currently have a same-name integration-test suite under tests/aws/services/; acm is recorded-real-AWS validated, while the auto-wired dynamodbstreams, transcribe, and s3tables providers are verified live against the emulator instead (evidence: probe-evidence-ts-gap-052.txt). At runtime, a plain make start serves the upstream LocalStack core provider for dynamodbstreams and transcribe, so the TotalStack variants are served only with PROVIDER_OVERRIDE_DYNAMODBSTREAMS=totalstack / PROVIDER_OVERRIDE_TRANSCRIBE=totalstack; s3tables has no upstream core or Moto backend and is pinned to the totalstack variant. The other 65 have no direct integration tests, so the code layout alone does not show which services are exercised by tests and which rely on the Moto fallback. Per-service status is tracked in docs/API.md.

Legend:

• tested - recorded-real-AWS validated: same-name integration-test suite at tests/aws/services/<service>/ with snapshot/validation data recorded against real AWS (currently only acm)
• auto-wired, live-verified - TotalStack provider auto-wired from the Speclang specs and verified live against the emulator (evidence: probe-evidence-ts-gap-052.txt); a plain make start serves the upstream LocalStack core provider, so serve the TotalStack variant with PROVIDER_OVERRIDE_<SVC>=totalstack
• live-verified, pinned - no recorded-real-AWS validated suite; verified live against the emulator (evidence: probe-evidence-ts-gap-052.txt) and pinned to the totalstack variant because upstream core has no provider (s3tables)
• Moto fallback - no same-name integration tests; unimplemented operations fall through to Moto where a backend exists

Please refer to GitHub releases to see the complete list of changes for each release. For extended release notes, please refer to the changelog.

If you are interested in contributing to LocalStack:

• Start by reading our contributing guide.
• Check out our development environment setup guide.
• Navigate our codebase and open issues.

We are thankful for all the contributions and feedback we receive.

Get in touch with the LocalStack Team to report 🐞 issues, upvote 👍 feature requests, 🙋🏽 ask support questions, or 🗣️ discuss local cloud development:

• LocalStack Slack Community
• LocalStack GitHub Issue tracker

We are thankful to all the people who have contributed to this project.

We are also grateful to all our backers who have donated to the project. You can become a backer on Open Collective.

You can also support this project by becoming a sponsor on Open Collective. Your logo will show up here along with a link to your website.

Copyright (c) 2017-2026 LocalStack maintainers and contributors.

Copyright (c) 2016 Atlassian and others.

This version of LocalStack is released under the Apache License, Version 2.0 (see LICENSE). By downloading and using this software you agree to the End-User License Agreement (EULA).