localemu 1.0.0__tar.gz

localemu-1.0.0/LICENSE

@@ -0,0 +1,15 @@
+Copyright (c) 2026 TocConsulting and LocalEmu contributors
+Copyright (c) 2017-2026 LocalEmu contributors
+Copyright (c) 2016 Atlassian Pty Ltd
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.

localemu-1.0.0/MANIFEST.in

@@ -0,0 +1,10 @@
+exclude .github/**
+exclude docs/**
+exclude tests/**
+exclude .test_durations
+exclude .gitignore
+exclude .pre-commit-config.yaml
+exclude .python-version
+include Makefile
+include LICENSE
+include NOTICE

localemu-1.0.0/Makefile

@@ -0,0 +1,151 @@
+IMAGE_NAME ?= localemu/localemu
+DEFAULT_TAG ?= latest
+VENV_BIN ?= python3 -m venv
+VENV_DIR ?= .venv
+PIP_CMD ?= pip3
+TEST_PATH ?= .
+TEST_EXEC ?= python -m
+PYTEST_LOGLEVEL ?= warning
+
+uname_m := $(shell uname -m)
+ifeq ($(uname_m),x86_64)
+PLATFORM ?= amd64
+else
+PLATFORM ?= arm64
+endif
+
+ifeq ($(OS), Windows_NT)
+	VENV_ACTIVATE = $(VENV_DIR)/Scripts/activate
+else
+	VENV_ACTIVATE = $(VENV_DIR)/bin/activate
+endif
+
+VENV_RUN = . $(VENV_ACTIVATE)
+
+usage:                    ## Show this help
+	@grep -Fh "##" $(MAKEFILE_LIST) | grep -Fv fgrep | sed -e 's/:.*##\s*/##/g' | awk -F'##' '{ printf "%-25s %s\n", $$1, $$2 }'
+
+$(VENV_ACTIVATE): pyproject.toml
+	test -d $(VENV_DIR) || $(VENV_BIN) $(VENV_DIR)
+	$(VENV_RUN); $(PIP_CMD) install --upgrade pip setuptools wheel
+	touch $(VENV_ACTIVATE)
+
+venv: $(VENV_ACTIVATE)    ## Create a new (empty) virtual environment
+
+freeze:                   ## Run pip freeze -l in the virtual environment
+	@$(VENV_RUN); pip freeze -l
+
+install-basic: venv       ## Install basic dependencies for CLI usage into venv
+	$(VENV_RUN); $(PIP_CMD) install $(PIP_OPTS) -e .
+
+install-runtime: venv     ## Install dependencies for the localemu runtime into venv
+	$(VENV_RUN); $(PIP_CMD) install $(PIP_OPTS) -e ".[runtime]"
+
+install-test: venv        ## Install requirements to run tests into venv
+	$(VENV_RUN); $(PIP_CMD) install $(PIP_OPTS) -e ".[test]"
+
+install-dev: venv         ## Install developer requirements into venv
+	$(VENV_RUN); $(PIP_CMD) install $(PIP_OPTS) -e ".[dev]"
+
+install-dev-types: venv   ## Install developer requirements incl. type hints into venv
+	$(VENV_RUN); $(PIP_CMD) install $(PIP_OPTS) -e ".[typehint]"
+
+install-s3: venv          ## Install dependencies for the localemu runtime for s3-only into venv
+	$(VENV_RUN); $(PIP_CMD) install $(PIP_OPTS) -e ".[base-runtime]"
+
+install: install-dev      ## Install full dependencies into venv
+
+entrypoints: install-dev
+	$(VENV_RUN); python -m plux entrypoints
+	@# make sure that the plux.ini file with the entrypoints has correctly been created
+	@test -s plux.ini || (echo "Entrypoints were not correctly created! Aborting!" && exit 1)
+
+dist:                     ## Build source and built (wheel) distributions of the current version
+	$(VENV_RUN); pip install --upgrade build twine; python -m build
+
+publish: clean-dist dist  ## Publish the library to the central PyPi repository
+	# make sure the dist archive contains a non-empty entry_points.txt file before uploading
+	tar --wildcards --to-stdout -xf dist/localemu*.tar.gz "localemu*/src/localemu.egg-info/entry_points.txt" | grep . > /dev/null 2>&1 || (echo "Refusing upload, localemu dist does not contain entrypoints." && exit 1)
+	$(VENV_RUN); twine upload dist/*
+
+coveralls:         		  ## Publish coveralls metrics
+	$(VENV_RUN); coveralls
+
+start:             		  ## Manually start the local infrastructure for testing
+	($(VENV_RUN); python3 -m localemu.runtime.main)
+
+docker-run-tests:		  ## Initializes the test environment and runs the tests in a docker container
+	docker run -e LOCALEMU_INTERNAL_TEST_COLLECT_METRIC=1 -e DOCKERHUB_USERNAME -e DOCKERHUB_PASSWORD --entrypoint= -v `pwd`/.git:/opt/code/localemu/.git -v `pwd`/.test_durations:/opt/code/localemu/.test_durations -v `pwd`/tests/:/opt/code/localemu/tests/ -v `pwd`/dist/:/opt/code/localemu/dist/ -v `pwd`/target/:/opt/code/localemu/target/ -v /var/run/docker.sock:/var/run/docker.sock -v /tmp/localemu:/var/lib/localemu  \
+		$(IMAGE_NAME):$(DEFAULT_TAG) \
+	    bash -c "make install-test && DEBUG=$(DEBUG) PYTEST_LOGLEVEL=$(PYTEST_LOGLEVEL) PYTEST_ARGS='$(PYTEST_ARGS)' COVERAGE_FILE='$(COVERAGE_FILE)' JUNIT_REPORTS_FILE=$(JUNIT_REPORTS_FILE) TEST_PATH='$(TEST_PATH)' LAMBDA_IGNORE_ARCHITECTURE=1 LAMBDA_INIT_POST_INVOKE_WAIT_MS=50 TINYBIRD_PYTEST_ARGS='$(TINYBIRD_PYTEST_ARGS)' TINYBIRD_DATASOURCE='$(TINYBIRD_DATASOURCE)' TINYBIRD_TOKEN='$(TINYBIRD_TOKEN)' TINYBIRD_URL='$(TINYBIRD_URL)' CI_REPOSITORY_NAME='$(CI_REPOSITORY_NAME)' CI_WORKFLOW_NAME='$(CI_WORKFLOW_NAME)' CI_COMMIT_BRANCH='$(CI_COMMIT_BRANCH)' CI_COMMIT_SHA='$(CI_COMMIT_SHA)' CI_JOB_URL='$(CI_JOB_URL)' CI_JOB_NAME='$(CI_JOB_NAME)' CI_JOB_ID='$(CI_JOB_ID)' CI='$(CI)' TEST_AWS_REGION_NAME='${TEST_AWS_REGION_NAME}' TEST_AWS_ACCESS_KEY_ID='${TEST_AWS_ACCESS_KEY_ID}' TEST_AWS_ACCOUNT_ID='${TEST_AWS_ACCOUNT_ID}' make test-coverage"
+
+docker-run-tests-s3-only:		  ## Initializes the test environment and runs the tests in a docker container for the S3 only image
+	# TODO: We need node as it's a dependency of the InfraProvisioner at import time, remove when we do not need it anymore
+	# g++ is a workaround to fix the JPype1 compile error on ARM Linux "gcc: fatal error: cannot execute ‘cc1plus’" because the test dependencies include the runtime dependencies.
+	docker run -e LOCALEMU_INTERNAL_TEST_COLLECT_METRIC=1 --entrypoint= -v `pwd`/.git:/opt/code/localemu/.git -v `pwd`/tests/:/opt/code/localemu/tests/ -v `pwd`/target/:/opt/code/localemu/target/ -v /var/run/docker.sock:/var/run/docker.sock -v /tmp/localemu:/var/lib/localemu \
+		$(IMAGE_NAME):$(DEFAULT_TAG) \
+	    bash -c "apt-get update && apt-get install -y g++ git && make install-test && apt-get install -y --no-install-recommends gnupg && mkdir -p /etc/apt/keyrings && curl -fsSL https://deb.nodesource.com/gpgkey/nodesource-repo.gpg.key | gpg --dearmor -o /etc/apt/keyrings/nodesource.gpg && echo \"deb [signed-by=/etc/apt/keyrings/nodesource.gpg] https://deb.nodesource.com/node_18.x nodistro main\" > /etc/apt/sources.list.d/nodesource.list && apt-get update && apt-get install -y --no-install-recommends nodejs && DEBUG=$(DEBUG) PYTEST_LOGLEVEL=$(PYTEST_LOGLEVEL) PYTEST_ARGS='$(PYTEST_ARGS)' TEST_PATH='$(TEST_PATH)' TINYBIRD_PYTEST_ARGS='$(TINYBIRD_PYTEST_ARGS)' TINYBIRD_DATASOURCE='$(TINYBIRD_DATASOURCE)' TINYBIRD_TOKEN='$(TINYBIRD_TOKEN)' TINYBIRD_URL='$(TINYBIRD_URL)' CI_COMMIT_BRANCH='$(CI_COMMIT_BRANCH)' CI_COMMIT_SHA='$(CI_COMMIT_SHA)' CI_JOB_URL='$(CI_JOB_URL)' CI_JOB_NAME='$(CI_JOB_NAME)' CI_JOB_ID='$(CI_JOB_ID)' CI='$(CI)' make test"
+
+
+docker-cp-coverage:
+	@echo 'Extracting .coverage file from Docker image'; \
+		id=$$(docker create localemu/localemu); \
+		docker cp $$id:/opt/code/localemu/.coverage .coverage; \
+		docker rm -v $$id
+
+test:              		  ## Run automated tests
+	($(VENV_RUN); $(TEST_EXEC) pytest --durations=10 --log-cli-level=$(PYTEST_LOGLEVEL) --junitxml=$(JUNIT_REPORTS_FILE) $(PYTEST_ARGS) $(TEST_PATH))
+
+test-coverage: LOCALEMU_INTERNAL_TEST_COLLECT_METRIC = 1
+test-coverage: TEST_EXEC = python -m coverage run $(COVERAGE_ARGS) -m
+test-coverage: test	  ## Run automated tests and create coverage report
+
+lint:              		  ## Run code linter to check code style, check if formatter would make changes and check if dependency pins need to be updated
+	@[ -f src/localemu/__init__.py ] && echo "src/localemu/__init__.py will break packaging." && exit 1 || :
+	($(VENV_RUN); python -m ruff check --output-format=full . && python -m ruff format --check --diff .)
+	$(VENV_RUN); pre-commit run check-pinned-deps-for-needed-upgrade --files pyproject.toml # run pre-commit hook manually here to ensure that this check runs in CI as well
+	$(VENV_RUN); openapi-spec-validator src/localemu/openapi.yaml
+	$(VENV_RUN); cd src && mypy --install-types --non-interactive
+	$(VENV_RUN); deptry .
+
+lint-modified:     		  ## Run code linter to check code style, check if formatter would make changes on modified files, and check if dependency pins need to be updated because of modified files
+	($(VENV_RUN); python -m ruff check --output-format=full `git diff --diff-filter=d --name-only HEAD | grep '\.py$$' | xargs` && python -m ruff format --check `git diff --diff-filter=d --name-only HEAD | grep '\.py$$' | xargs`)
+	$(VENV_RUN); pre-commit run check-pinned-deps-for-needed-upgrade --files $(git diff main --name-only) # run pre-commit hook manually here to ensure that this check runs in CI as well
+
+check-aws-markers:     		  ## Lightweight check to ensure all AWS tests have proper compatibility markers set
+	($(VENV_RUN); python -m pytest --co tests/aws/)
+
+format:            		  ## Run ruff to format the whole codebase
+	($(VENV_RUN); python -m ruff check --output-format=full --fix .; python -m ruff format .)
+
+format-modified:          ## Run ruff to format only modified code
+	($(VENV_RUN); \
+	  python -m ruff check --output-format=full --fix `git diff --diff-filter=d --name-only HEAD | grep '\.py$$' | xargs`; \
+	  python -m ruff format `git diff --diff-filter=d --name-only HEAD | grep '\.py$$' | xargs`)
+
+asf-regenerate:                   ## Regenerate ASF APIs
+	$(VENV_RUN); python -m localemu.aws.scaffold upgrade
+	@echo 'Removing unused imports from generated modules'
+	$(VENV_RUN); python -m ruff check --select F401 --unsafe-fixes --fix src/localemu/aws/api/ --config "lint.preview = true"
+	$(VENV_RUN); python -m ruff check --output-format=full --fix src/localemu/aws/api/
+	$(VENV_RUN); python -m ruff format src/localemu/aws/api/
+
+init-precommit:    		  ## install te pre-commit hook into your local git repository
+	($(VENV_RUN); pre-commit install)
+
+docker-build:
+	IMAGE_NAME=$(IMAGE_NAME) PLATFORM=$(PLATFORM) ./bin/docker-helper.sh build
+
+clean:             		  ## Clean up (npm dependencies, downloaded infrastructure code, compiled Java classes)
+	rm -rf .filesystem
+	rm -rf build/
+	rm -rf dist/
+	rm -rf *.egg-info
+	rm -rf src/*.egg-info
+	rm -rf $(VENV_DIR)
+
+clean-dist:				  ## Clean up python distribution directories
+	rm -rf dist/ build/
+	rm -rf src/*.egg-info
+
+.PHONY: usage freeze install-basic install-runtime install-test install-dev install entrypoints dist publish coveralls start docker-run-tests docker-cp-coverage test test-coverage lint lint-modified format format-modified asf-regenerate init-precommit clean clean-dist upgrade-pinned-dependencies

localemu-1.0.0/NOTICE

@@ -0,0 +1,15 @@
+LocalEmu
+Copyright (c) 2026 TocConsulting and LocalEmu contributors
+
+This product includes software developed by LocalStack Inc. and contributors
+(Copyright (c) 2017-2026 LocalStack Inc and contributors), originally
+released under the Apache License, Version 2.0. LocalEmu is a community
+fork of the archived LocalStack community edition.
+
+This product also includes portions originally developed by Atlassian Pty Ltd
+(Copyright (c) 2016 Atlassian Pty Ltd), released under the Apache License,
+Version 2.0, from which LocalStack itself was originally derived.
+
+The full Apache License, Version 2.0 is reproduced in the LICENSE file at
+the root of this repository, together with the preserved copyright lines
+listed above.

localemu-1.0.0/PKG-INFO

@@ -0,0 +1,464 @@
+Metadata-Version: 2.4
+Name: localemu
+Version: 1.0.0
+Summary: The core library and runtime of LocalEmu
+Author-email: LocalEmu Contributors <info@localemu.cloud>
+License-Expression: Apache-2.0
+Project-URL: Homepage, https://localemu.cloud
+Project-URL: Documentation, https://localemu.cloud/docs
+Project-URL: Repository, https://github.com/localemu/localemu.git
+Project-URL: Issues, https://github.com/localemu/localemu/issues
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Internet
+Classifier: Topic :: Software Development :: Testing
+Classifier: Topic :: System :: Emulators
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+License-File: NOTICE
+Requires-Dist: asn1crypto>=1.5.1
+Requires-Dist: click>=8.2.0
+Requires-Dist: cachetools>=5.0
+Requires-Dist: cryptography>=46.0.7
+Requires-Dist: PyJWT[crypto]>=2.8.0
+Requires-Dist: dnspython>=1.16.0
+Requires-Dist: plux>=1.14.0
+Requires-Dist: psutil>=5.4.8
+Requires-Dist: python-dotenv>=0.19.1
+Requires-Dist: pyyaml>=5.1
+Requires-Dist: rich>=12.3.0
+Requires-Dist: requests>=2.20.0
+Requires-Dist: semver>=2.10
+Provides-Extra: base-runtime
+Requires-Dist: boto3==1.42.59; extra == "base-runtime"
+Requires-Dist: botocore==1.42.59; extra == "base-runtime"
+Requires-Dist: awscrt!=0.27.1,>=0.13.14; extra == "base-runtime"
+Requires-Dist: cbor2>=6.0; extra == "base-runtime"
+Requires-Dist: dill==0.3.6; extra == "base-runtime"
+Requires-Dist: dnspython>=1.16.0; extra == "base-runtime"
+Requires-Dist: docker>=6.1.1; extra == "base-runtime"
+Requires-Dist: jsonpatch>=1.24; extra == "base-runtime"
+Requires-Dist: jsonpointer>=3.0.0; extra == "base-runtime"
+Requires-Dist: jsonschema>=4.25.1; extra == "base-runtime"
+Requires-Dist: hypercorn>=0.14.4; extra == "base-runtime"
+Requires-Dist: Twisted[tls]>=26.4.0; extra == "base-runtime"
+Requires-Dist: openapi-core>=0.19.2; extra == "base-runtime"
+Requires-Dist: pydantic>=2.11.9; extra == "base-runtime"
+Requires-Dist: pyopenssl>=23.0.0; extra == "base-runtime"
+Requires-Dist: python-dateutil>=2.9.0; extra == "base-runtime"
+Requires-Dist: readerwriterlock>=1.0.7; extra == "base-runtime"
+Requires-Dist: requests-aws4auth>=1.0; extra == "base-runtime"
+Requires-Dist: urllib3>=2.7.0; extra == "base-runtime"
+Requires-Dist: Werkzeug>=3.1.3; extra == "base-runtime"
+Requires-Dist: xmltodict>=0.13.0; extra == "base-runtime"
+Requires-Dist: rolo>=0.8.1; extra == "base-runtime"
+Provides-Extra: runtime
+Requires-Dist: localemu[base-runtime]; extra == "runtime"
+Requires-Dist: awscli==1.44.49; extra == "runtime"
+Requires-Dist: airspeed-ext>=0.6.3; extra == "runtime"
+Requires-Dist: antlr4-python3-runtime==4.13.2; extra == "runtime"
+Requires-Dist: apispec>=5.1.1; extra == "runtime"
+Requires-Dist: aws-sam-translator>=1.105.0; extra == "runtime"
+Requires-Dist: crontab>=0.22.6; extra == "runtime"
+Requires-Dist: cryptography>=46.0.7; extra == "runtime"
+Requires-Dist: jinja2>=3.1.6; extra == "runtime"
+Requires-Dist: jsonpath-ng==1.7.0; extra == "runtime"
+Requires-Dist: jsonpath-rw>=1.4.0; extra == "runtime"
+Requires-Dist: moto-ext[all]>=5.1.22; extra == "runtime"
+Requires-Dist: opensearch-py>=2.4.1; extra == "runtime"
+Requires-Dist: duckdb>=1.0; extra == "runtime"
+Requires-Dist: sqlglot>=23; extra == "runtime"
+Requires-Dist: pymongo>=4.2.0; extra == "runtime"
+Requires-Dist: PyJWT[crypto]>=2.8.0; extra == "runtime"
+Requires-Dist: pyopenssl>=23.0.0; extra == "runtime"
+Requires-Dist: responses>=0.25.8; extra == "runtime"
+Provides-Extra: test
+Requires-Dist: localemu[runtime]; extra == "test"
+Requires-Dist: coverage[toml]>=5.5; extra == "test"
+Requires-Dist: httpx[http2]>=0.25; extra == "test"
+Requires-Dist: json5>=0.12.1; extra == "test"
+Requires-Dist: pluggy>=1.3.0; extra == "test"
+Requires-Dist: pytest>=7.4.2; extra == "test"
+Requires-Dist: pytest-split>=0.8.0; extra == "test"
+Requires-Dist: pytest-httpserver>=1.1.2; extra == "test"
+Requires-Dist: pytest-rerunfailures>=12.0; extra == "test"
+Requires-Dist: pytest-tinybird>=0.5.0; extra == "test"
+Requires-Dist: aws-cdk-lib>=2.88.0; extra == "test"
+Requires-Dist: websocket-client>=1.7.0; extra == "test"
+Requires-Dist: deepdiff; extra == "test"
+Requires-Dist: jsonpath-ng>1.6; extra == "test"
+Requires-Dist: pika>=1.3; extra == "test"
+Requires-Dist: kafka-python>=2.0; extra == "test"
+Provides-Extra: dev
+Requires-Dist: localemu[test]; extra == "dev"
+Requires-Dist: coveralls>=3.3.1; extra == "dev"
+Requires-Dist: deptry>=0.13.0; extra == "dev"
+Requires-Dist: Cython; extra == "dev"
+Requires-Dist: networkx>=2.8.4; extra == "dev"
+Requires-Dist: openapi-spec-validator>=0.7.1; extra == "dev"
+Requires-Dist: pandoc; extra == "dev"
+Requires-Dist: pre-commit>=3.5.0; extra == "dev"
+Requires-Dist: pypandoc; extra == "dev"
+Requires-Dist: ruff>=0.3.3; extra == "dev"
+Requires-Dist: rstr>=3.2.0; extra == "dev"
+Requires-Dist: mypy; extra == "dev"
+Requires-Dist: watchdog>=6; extra == "dev"
+Provides-Extra: typehint
+Requires-Dist: localemu[dev]; extra == "typehint"
+Requires-Dist: boto3-stubs[acm,acm-pca,amplify,apigateway,apigatewayv2,appconfig,appconfigdata,application-autoscaling,appsync,athena,autoscaling,backup,batch,ce,cloudcontrol,cloudformation,cloudfront,cloudtrail,cloudwatch,codebuild,codecommit,codeconnections,codedeploy,codepipeline,codestar-connections,cognito-identity,cognito-idp,dms,docdb,dynamodb,dynamodbstreams,ec2,ecr,ecs,efs,eks,elasticache,elasticbeanstalk,elbv2,emr,emr-serverless,es,events,firehose,fis,glacier,glue,iam,identitystore,iot,iot-data,iotwireless,kafka,kinesis,kinesisanalyticsv2,kms,lakeformation,lambda,logs,managedblockchain,mediaconvert,mq,mwaa,neptune,opensearch,organizations,pi,pinpoint,pipes,rds,rds-data,redshift,redshift-data,resource-groups,resourcegroupstaggingapi,route53,route53resolver,s3,s3control,sagemaker,sagemaker-runtime,secretsmanager,serverlessrepo,servicediscovery,ses,sesv2,sns,sqs,ssm,sso-admin,stepfunctions,sts,timestream-query,timestream-write,transcribe,verifiedpermissions,wafv2,xray]; extra == "typehint"
+Dynamic: license-file
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/localemu/localemu/main/docs/localemu-logo.png" alt="LocalEmu" width="120">
+</p>
+
+<h1 align="center">LocalEmu</h1>
+
+<p align="center">
+  A free, open-source AWS cloud emulator.
+</p>
+
+<p align="center">
+  <a href="https://pypi.org/project/localemu/"><img alt="PyPI" src="https://img.shields.io/pypi/v/localemu?color=blue"></a>
+  <a href="https://pypi.org/project/localemu/"><img alt="Python versions" src="https://img.shields.io/pypi/pyversions/localemu"></a>
+  <a href="https://hub.docker.com/r/localemu/localemu"><img alt="Docker Pulls" src="https://img.shields.io/docker/pulls/localemu/localemu"></a>
+  <a href="https://github.com/localemu/localemu/blob/main/LICENSE"><img alt="License: Apache 2.0" src="https://img.shields.io/badge/license-Apache%202.0-blue.svg"></a>
+</p>
+
+<p align="center">
+  <img alt="Emulates AWS" src="https://img.shields.io/badge/emulates-AWS-FF9900?logo=amazonwebservices&logoColor=white">
+  <img alt="AWS services" src="https://img.shields.io/badge/AWS%20services-132-1f6feb">
+  <a href="https://github.com/localemu/localemu/blob/main/CONTRIBUTING.md"><img alt="PRs welcome" src="https://img.shields.io/badge/PRs-welcome-brightgreen.svg"></a>
+  <a href="https://github.com/astral-sh/ruff"><img alt="Ruff" src="https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json"></a>
+  <a href="https://github.com/localemu/localemu/stargazers"><img alt="GitHub stars" src="https://img.shields.io/github/stars/localemu/localemu?color=yellow"></a>
+</p>
+
+<p align="center">
+  Run AWS services locally. No account. No token. No sign-up.
+</p>
+
+---
+
+## What is LocalEmu?
+
+LocalEmu emulates 132 AWS services on your machine. Use the same AWS CLI, boto3, Terraform, or CDK you already know - just point to `localhost:4566`.
+
+**Build and test against AWS APIs from your laptop with no account, no credentials, no internet.** The iteration loop is seconds instead of minutes; you can break, reset, and rebuild as often as you want at zero cost.
+
+Where it counts, the behavior is real, not stubbed: Lambda runs your code in the official AWS runtime images, EC2 instances are real containers on a real VPC with security groups enforced by actual packet filtering, RDS is a real PostgreSQL or MySQL you can open a connection to, and (with `IAM_ENFORCEMENT=1`) your identity and resource policies actually deny.
+
+## Install
+
+```bash
+pip install localemu[runtime]
+```
+
+That's it. No Java. No tokens. No accounts. Docker is required for services that emulate by running a real engine in a sidecar (Lambda, ECS, EKS via k3d, RDS, OpenSearch, EC2). Everything else is pure Python and needs no Docker.
+
+## Start
+
+```bash
+# Foreground (see the banner and logs)
+localemu start
+
+# Detached mode (runs in background)
+localemu start -d
+
+# Custom port
+localemu start --port 4567
+
+# Stop
+localemu stop
+```
+
+## Use
+
+LocalEmu ships `awsemu` - a drop-in replacement for the AWS CLI that automatically points to LocalEmu. No configuration needed:
+
+```bash
+# S3
+awsemu s3 mb s3://my-bucket
+awsemu s3 cp file.txt s3://my-bucket/
+
+# DynamoDB
+awsemu dynamodb create-table --table-name Users \
+  --key-schema AttributeName=id,KeyType=HASH \
+  --attribute-definitions AttributeName=id,AttributeType=S \
+  --billing-mode PAY_PER_REQUEST
+
+# SQS
+awsemu sqs create-queue --queue-name my-queue
+
+# Lambda
+awsemu lambda create-function --function-name hello \
+  --runtime python3.12 --handler handler.handler \
+  --role arn:aws:iam::000000000000:role/role \
+  --zip-file fileb://function.zip
+
+# Any of the 132 supported services...
+awsemu ecs create-cluster --cluster-name my-cluster
+awsemu rds describe-db-instances
+awsemu cognito-idp create-user-pool --pool-name my-pool
+```
+
+`awsemu` sets credentials, region, and endpoint automatically. You can also use the standard AWS CLI, boto3, Terraform, CDK, or Pulumi - just point to `http://localhost:4566`.
+
+## Documentation & examples
+
+The full documentation lives at [localemu.cloud/docs](https://localemu.cloud/docs): prerequisites, install guide, per-service API reference, and end-to-end use case walkthroughs.
+
+For runnable code, clone the companion examples repository:
+
+```bash
+git clone https://github.com/localemu/localemu-examples
+```
+
+It ships self-contained tutorials covering common patterns: public + private VPC with EC2 / nginx / NACL, image pipelines, scheduled jobs, IAM least-privilege drills, Step Functions sagas, EKS + kubectl, chaos resilience tests, and more.
+
+## Explore
+
+```bash
+# List all supported services
+localemu services
+
+# Show operations for a specific service
+localemu services s3
+localemu services lambda
+localemu services dynamodb
+
+# Check running services
+localemu status
+
+# Stop
+localemu stop
+```
+
+## Dashboard
+
+LocalEmu includes a built-in web dashboard for monitoring and exploring your local AWS environment in real time.
+
+```
+http://localhost:4566/_localemu/dashboard
+```
+
+The dashboard shows:
+- **Service overview** with resource counts and status indicators for all active services
+- **Resource drill-down**: click any service to see tables, buckets, queues, functions, instances, and more
+- **S3 object browser** and **DynamoDB item viewer** with click-through navigation
+- **CloudTrail event history** with expandable request/response details
+- **Live activity feed** showing API calls as they happen, filterable by service
+
+The dashboard starts automatically with LocalEmu. No configuration needed.
+
+## Simulation Features
+
+Test real AWS behavior locally with opt-in feature flags:
+
+```bash
+# IAM policy enforcement (full AWS evaluation algorithm, see section below)
+IAM_ENFORCEMENT=1 localemu start
+
+# API throttling simulation (per-service AWS error codes)
+SIMULATE_THROTTLING=1 THROTTLE_RATE=0.05 localemu start
+
+# Network latency injection (realistic per-service delays)
+SIMULATE_LATENCY=1 localemu start
+
+# Lambda cold start simulation
+LAMBDA_COLD_START_DELAY=3 localemu start
+
+# EC2, ECS, and EKS use real containers automatically when Docker is
+# available; no env var needed. Opt out via EC2_VM_MANAGER=none,
+# ECS_DOCKER_BACKEND=0, or EKS_K8S_PROVIDER=off.
+
+# Real RDS engines (PostgreSQL / MySQL / MariaDB in containers)
+RDS_DOCKER_BACKEND=1 localemu start
+```
+
+Simulation features (IAM enforcement, throttling, latency, cold-start) are disabled by default; zero overhead when off. The container-backed services turn themselves off automatically when the Docker daemon is unavailable.
+
+## IAM Policy Enforcement
+
+Run your AWS workload against the same policy rules AWS applies in production. Useful for catching permission errors locally before they surface in a deployed environment.
+
+```bash
+# Strict mode: deny unauthorized requests with 403 AccessDenied
+IAM_ENFORCEMENT=1 localemu start
+
+# Audit mode: log would-be denials, allow the request through
+IAM_ENFORCEMENT=soft localemu start
+
+# Bypass enforcement for specific access keys (comma-separated allow-list)
+ROOT_ACCESS_KEYS=AKIAIOSFODNN7EXAMPLE IAM_ENFORCEMENT=1 localemu start
+```
+
+**What gets evaluated** (full AWS algorithm, see [policy evaluation logic](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_evaluation-logic.html)):
+
+- Explicit `Deny` in any policy → deny (identity / resource / permission boundary / session).
+- Same-account: either identity-policy `Allow` OR resource-policy `Allow` is sufficient.
+- Permission boundary: must also `Allow` (intersection).
+- Session policies (inline or managed) passed via `AssumeRole`: must also `Allow` (intersection).
+
+**Policy elements**
+
+| Element | Supported |
+|---|---|
+| `Action` / `NotAction` with wildcards `*` `?` | ✅ |
+| `Resource` / `NotResource` ARN matching | ✅ |
+| `Principal` / `NotPrincipal` (AWS / Service / Federated / CanonicalUser) | ✅ |
+| IAM policy variables: `${aws:username}`, `${aws:userid}`, `${aws:PrincipalTag/*}` | ✅ |
+| String / Numeric / Date / IpAddress / Bool / Arn / Null operators | ✅ |
+| `IfExists` suffix | ✅ |
+| `ForAllValues:` / `ForAnyValue:` set operators | ✅ |
+
+**Condition context keys populated per request**
+
+`aws:PrincipalArn`, `aws:PrincipalAccount`, `aws:PrincipalType`, `aws:SourceIp`, `aws:CurrentTime`, `aws:EpochTime`, `aws:SecureTransport` (from TLS scheme), `aws:UserAgent`, `aws:RequestedRegion`, `aws:username`, `aws:userid`, `aws:PrincipalTag/*`, `aws:RequestTag/*`, `aws:TagKeys`, and `aws:MultiFactorAuthPresent` (set to `"true"` only when the caller's session was minted by `AssumeRole` / `GetSessionToken` with `--serial-number`, otherwise absent per AWS spec).
+
+**Temporary-credential validation**: temporary access keys (`ASIA*` / `LSIA*`) must include an `X-Amz-Security-Token`. Expired sessions return `ExpiredTokenException`.
+
+**Limitations**
+
+- Cross-account calls (caller account ≠ resource owner account) are currently treated as same-account. LocalEmu defaults to a single account so this rarely matters; if you emulate multi-account IAM flows, enforcement will be more permissive than AWS.
+- Service-principal grants on resource policies (e.g. `Principal: {Service: lambda.amazonaws.com}`) are not auto-matched for internal service-to-service calls; use `AWS` principals or `*` for now.
+
+## 132 Supported Services
+
+Run `localemu services` to see the full list. Key services include: ACM, API Gateway, AppSync, Athena, Backup, Batch, Bedrock, CloudFormation, CloudFront, CloudTrail, CloudWatch, CodeBuild, CodeCommit, CodeDeploy, CodePipeline, Cognito, Config, DynamoDB, EC2, ECR, ECS, EFS, EKS, ElastiCache, ELB, ELBv2, Elasticsearch, EMR, EventBridge, Firehose, FSx, Glacier, Glue, GuardDuty, IAM, IoT, Kafka, Kinesis, KMS, Lambda, CloudWatch Logs, Neptune, OpenSearch, Organizations, Pipes, RDS, Redshift, Rekognition, Resource Groups, Route53, S3, SageMaker, Scheduler, Secrets Manager, SES, SESv2, SNS, SQS, SSM, Step Functions, STS, Textract, Transcribe, Transfer, WAFv2, X-Ray, and more.
+
+## Python (boto3)
+
+```python
+import boto3
+
+s3 = boto3.client("s3",
+    endpoint_url="http://localhost:4566",
+    aws_access_key_id="AKIAIOSFODNN7EXAMPLE",
+    aws_secret_access_key="wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY",
+    region_name="us-east-1",
+)
+
+s3.create_bucket(Bucket="my-bucket")
+s3.put_object(Bucket="my-bucket", Key="hello.txt", Body=b"Hello!")
+```
+
+## Terraform
+
+```hcl
+provider "aws" {
+  access_key                  = "AKIAIOSFODNN7EXAMPLE"
+  secret_key                  = "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY"
+  region                      = "us-east-1"
+  skip_credentials_validation = true
+  skip_metadata_api_check     = true
+
+  endpoints {
+    s3       = "http://localhost:4566"
+    dynamodb = "http://localhost:4566"
+    lambda   = "http://localhost:4566"
+    sqs      = "http://localhost:4566"
+    # all services on the same endpoint
+  }
+}
+```
+
+## Persistence
+
+By default, LocalEmu state is ephemeral. To keep your resources across restarts:
+
+```bash
+# Local
+PERSISTENCE=1 localemu start
+
+# Docker
+docker run -d --name localemu \
+  -p 4566:4566 \
+  -v localemu-data:/var/lib/localemu \
+  -e PERSISTENCE=1 \
+  --user root \
+  localemu/localemu
+```
+
+State is saved on shutdown and restored on startup. S3 buckets, DynamoDB tables,
+Lambda functions, SQS queues, Secrets Manager secrets. Everything survives.
+
+**Save strategies** (set via `SNAPSHOT_SAVE_STRATEGY`):
+- `ON_SHUTDOWN` (default): saves when LocalEmu stops
+- `SCHEDULED`: saves every 15 seconds (configurable via `SNAPSHOT_FLUSH_INTERVAL`)
+- `MANUAL`: save/load via `POST /_localemu/state/save` and `POST /_localemu/state/load`
+
+**Check status:** `GET /_localemu/state/status`
+
+## Docker (alternative)
+
+```bash
+# Linux
+docker run --rm -d -p 4566:4566 -p 4510-4559:4510-4559 \
+  -v /var/run/docker.sock:/var/run/docker.sock \
+  --group-add docker \
+  localemu/localemu
+
+# macOS (Docker Desktop)
+docker run --rm -d -p 4566:4566 -p 4510-4559:4510-4559 \
+  -v /var/run/docker.sock:/var/run/docker.sock \
+  --user root \
+  localemu/localemu
+```
+
+> **Why `--user root` on macOS?** Lambda, ECS, and EC2 services spawn real
+> Docker containers for function execution. On Docker Desktop for Mac the
+> socket is owned by `root` inside the container regardless of host GID, so
+> the non-root `localemu` user cannot access it. On Linux, adding the
+> `docker` group (`--group-add docker`) is sufficient.
+
+## Using the AWS CLI with Docker
+
+When LocalEmu runs in Docker, use the standard AWS CLI from your host:
+
+```bash
+# Option A: set the endpoint once via env var (recommended)
+export AWS_ENDPOINT_URL=http://localhost:4566
+export AWS_ACCESS_KEY_ID=AKIAIOSFODNN7EXAMPLE
+export AWS_SECRET_ACCESS_KEY=wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY
+export AWS_DEFAULT_REGION=us-east-1
+
+aws s3 ls
+aws dynamodb list-tables
+aws lambda list-functions
+```
+
+```bash
+# Option B: create a host-side awsemu alias
+alias awsemu='aws --endpoint-url=http://localhost:4566 --region us-east-1'
+export AWS_ACCESS_KEY_ID=AKIAIOSFODNN7EXAMPLE
+export AWS_SECRET_ACCESS_KEY=wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY
+
+awsemu s3 ls
+awsemu sqs list-queues
+```
+
+```bash
+# Option C: use awsemu inside the container
+docker exec localemu bash -c \
+  '. /opt/code/localemu/.venv/bin/activate && awsemu s3 ls'
+```
+
+> **Tip:** Option A with `AWS_ENDPOINT_URL` is the cleanest: boto3 and the
+> AWS CLI both read it automatically. Your code works identically on LocalEmu
+> and real AWS by just unsetting the env var.
+
+## Contributing
+
+- [Open issues](https://github.com/localemu/localemu/issues)
+- [Discussions](https://github.com/localemu/localemu/discussions)
+
+## License
+
+Copyright (c) 2026 TocConsulting and LocalEmu contributors.
+Copyright (c) 2017-2026 LocalStack contributors.
+Copyright (c) 2016 Atlassian and others.
+
+Apache License, Version 2.0. See [LICENSE](LICENSE) and [NOTICE](NOTICE).
+
+LocalEmu is a fork of [LocalStack](https://github.com/localstack/localstack), which was archived by its maintainers. We are grateful to all original contributors.