Environment Variables
Complete reference for the 125 environment variables LocalEmu reads from
src/localemu/config.py. Set them before starting the process or pass them
with docker run -e.
This table is generated from the source file by
scripts/gen_env_vars.py. If you spot a drift between docs and code,
re-run the generator and open a PR.
Public knobs (18)
Documented user-facing variables. Safe to set in production-like local environments.
| Variable | Default | Description |
|---|---|---|
HOSTNAME_FROM_LAMBDA core | (unset) | Endpoint host under which LocalEmu APIs are accessible from Lambda Docker containers. |
LAMBDA_COLD_START_DELAY lambda | 0 | 0 (disabled by default) Artificial cold start delay in seconds applied to the first invocation of a function version (or after it has been idle longer than LAMBDA_COLD_START_IDLE_TIMEOUT). Set to a positive value (e.g. 3) to simulate AWS Lambda cold start latency. |
LAMBDA_COLD_START_IDLE_TIMEOUT lambda | 300 | 300 (default 5 min, matching AWS) Idle time in seconds after which a function version is considered cold again. |
LAMBDA_DEBUG_MODE lambda | 0 | PREVIEW: 0 (default), 1 (preview) When enabled it triggers specialised workflows for the debugging. |
LAMBDA_DISABLE_AWS_ENDPOINT_URL lambda | 0 | Opt-out to inject the environment variable AWS_ENDPOINT_URL for automatic configuration of AWS SDKs: https://docs.aws.amazon.com/sdkref/latest/guide/feature-ss-endpoints.html |
LAMBDA_DOCKER_FLAGS lambda | (unset) | -e KEY=VALUE -v host:container Additional flags passed to Docker run|create commands. |
LAMBDA_DOCKER_NETWORK lambda | (unset) | bridge (Docker default) Docker network driver for the Lambda and ECS containers. https://docs.docker.com/network/ |
LAMBDA_IGNORE_ARCHITECTURE lambda | 0 | 0 (default) Enable this flag to run cross-platform compatible lambda functions natively (i.e., Docker selects architecture) and ignore the AWS architectures (i.e., x86_64, arm64) configured for the lambda function. |
LAMBDA_JAVA_OPTS lambda | (unset) | v1: -Xmx512M (example) Currently not supported in new provider but possible via custom entrypoint. Allow passing custom JVM options to Java Lambdas executed in Docker. |
LAMBDA_KEEPALIVE_MS lambda | 600_000 | 600000 (default 10min) Time in milliseconds until lambda shuts down the execution environment after the last invocation has been processed. Set to 0 to immediately shut down the execution environment after an invocation. |
LAMBDA_LIMITS_CODE_SIZE_ZIPPED lambda | 52_428_800 | documented after AWS changed validation around 2023-11 |
LAMBDA_RUNTIME_ENVIRONMENT_TIMEOUT lambda | (unset) | 20 (default) How many seconds Lambda will wait for the runtime environment to start up. |
LAMBDA_RUNTIME_EXECUTOR lambda | CONTAINER_RUNTIME | docker (default), kubernetes (pro) Where Lambdas will be executed. |
LAMBDA_RUNTIME_IMAGE_MAPPING lambda | (unset) | base images for Lambda (default) https://docs.aws.amazon.com/lambda/latest/dg/runtimes-images.html localemu/services/lambda_/invocation/lambda_models.py:IMAGE_MAPPING Customize the Docker image of Lambda runtimes, either by: a) pattern with <runtime> placeholder, e.g. custom-repo/lambda-<runtime>:2022 b) json dict mapping the <runtime> to an image, e.g. {"python3.9": "custom-repo/lambda-py:thon... |
LAMBDA_RUNTIME_VALIDATION lambda | (unset) | 0 (default) Whether to disable usage of deprecated runtimes |
LAMBDA_SYNCHRONOUS_CREATE lambda | 0 | 0 (default) Set to 1 to create lambda functions synchronously (not recommended). Whether Lambda.CreateFunction will block until the function is in a terminal state (Active or Failed). This technically breaks behavior parity but is provided as a simplification over the default AWS behavior and to match the behavior of the old lambda provider. |
LAMBDA_TRUNCATE_STDOUT lambda | (unset) | 2000 (default) Allows increasing the default char limit for truncation of lambda log lines when printed in the console. This does not affect the logs processing in CloudWatch. |
S3_STRICT_PRESIGNED_VALIDATION s3 | 0 | false (default) When true, presigned URL validation will NOT fall back to the hardcoded "test" access key / secret when the request's access key is not registered in LocalEmu. Unregistered keys will be rejected. Enable this for Production-parity testing . |
Experimental (3)
Preview features that may change between releases.
| Variable | Default | Description |
|---|---|---|
CFN_IGNORE_UNSUPPORTED_RESOURCE_TYPES cloudformation | 1 | How localemu will react to encountering unsupported resource types. By default unsupported resource types will be ignored. |
LOG_LEVEL_OVERRIDES core | (unset) | allow setting custom log levels for individual loggers |
LAMBDA_PREBUILD_IMAGES lambda | 0 | TODO: test and add to docs 0 (default) prebuild images before execution? Increased cold start time on the tradeoff of increased time until lambda is ACTIVE |
Development / debug (8)
Debugger / Delve / runtime-init hooks. Useful when developing against LocalEmu, not for normal use.
| Variable | Default | Description |
|---|---|---|
LAMBDA_INIT_BIN_PATH lambda-init | (unset) | path to RIE init binary (e.g., var/rapid/init) |
LAMBDA_INIT_BOOTSTRAP_PATH lambda-init | (unset) | path to entrypoint script (e.g., var/rapid/entrypoint.sh) |
LAMBDA_INIT_DEBUG lambda-init | 0 | 0 (default) Enable for mounting of RIE init binary and delve debugger |
LAMBDA_INIT_DELVE_PATH lambda-init | (unset) | path to delve debugger (e.g., var/rapid/dlv) |
LAMBDA_INIT_DELVE_PORT lambda-init | (unset) | Go Delve debug port |
LAMBDA_INIT_POST_INVOKE_WAIT_MS lambda-init | (unset) | Time to wait after every invoke as a workaround to fix a race condition in persistence tests |
LAMBDA_INIT_RELEASE_VERSION lambda-init | (unset) | Release version of https://github.com/localemu/lambda-runtime-init overriding the current default |
LAMBDA_INIT_USER lambda-init | (unset) | sbx_user1051 (default when not provided) Alternative system user or empty string to skip dropping privileges. |
CLI configuration (2)
Override the configuration profile or directory the CLI loads.
| Variable | Default | Description |
|---|---|---|
CONFIG_DIR core | os.path.expanduser("~/.localemu | host configuration directory |
CONFIG_PROFILE core | (unset) | the configuration profile to load |
Advanced (uncategorised) (94)
Less-documented switches surfaced for completeness. Set only if you know why.
| Variable | Default | Description |
|---|---|---|
APIGW_NEXT_GEN_PROVIDER apigateway | (unset) | Whether the Next Gen APIGW invocation logic is enabled (on by default) |
CFN_PER_RESOURCE_TIMEOUT cloudformation | (unset) | Set the timeout to deploy each individual CloudFormation resource |
CFN_VERBOSE_ERRORS cloudformation | 0 | Show exceptions for CloudFormation deploy errors |
ALLOW_NONSTANDARD_REGIONS core | 0 | Allow non-standard AWS regions |
BOTO_WAITER_DELAY core | (unset) | (no description in config.py - see source) |
BOTO_WAITER_MAX_ATTEMPTS core | (unset) | (no description in config.py - see source) |
CUSTOM_SSL_CERT_PATH core | (unset) | Absolute path to a custom certificate (pem file) |
DATA_DIR core | (unset) | directory for persisting data (TODO: deprecated, simply use PERSISTENCE=1) |
DEBUG core | 0 | (no description in config.py - see source) |
DEBUG_HANDLER_CHAIN core | 0 | whether to log fine-grained debugging information for the handler chain |
DEVELOP core | 0 | whether to enable debugpy |
DEVELOP_PORT core | (unset) | PORT FOR DEBUGGER |
DISABLE_BOTO_RETRIES core | 0 | defaults to false if `DISABLE_BOTO_RETRIES=1` is set, all our created boto clients will have retries disabled |
DISABLE_CORS_CHECKS core | 0 | (no description in config.py - see source) |
DISABLE_CORS_HEADERS core | 0 | CORS settings |
DISABLE_CUSTOM_BOTO_WAITER_CONFIG core | 0 | (no description in config.py - see source) |
DISABLE_CUSTOM_CORS_APIGATEWAY core | 0 | (no description in config.py - see source) |
DISABLE_CUSTOM_CORS_S3 core | 0 | (no description in config.py - see source) |
DISABLE_PREFLIGHT_PROCESSING core | 0 | (no description in config.py - see source) |
GATEWAY_SERVER core | (unset) | the gateway server that should be used (supported: hypercorn, twisted dev: werkzeug) |
GATEWAY_WORKER_COUNT core | (unset) | (no description in config.py - see source) |
LOCALEMU_BUILD_DATE core | (unset) | the date on which the docker image was created |
LOCALEMU_BUILD_GIT_HASH core | (unset) | the latest commit id of the repository when the docker image was created |
LOCALEMU_ENI_REAL core | 1 | When enabled, Elastic Network Interface operations (create, attach, detach, delete, assign and unassign private IPs, modify attributes, describe) apply real network changes inside the EC2 container instead of returning metadata-only responses. Requires LOCALEMU_VPC_IP_PINNING (also default-on) ; if that prereq is set false explicitly, this flag is treated as off and a warning is logged. Default... |
LOCALEMU_RESPONSE_HEADER_ENABLED core | 1 | This flag enables all responses from LocalEmu to contain a `x-localemu` HTTP header. |
LOCALEMU_VPC_IP_PINNING core | 1 | When enabled, VPC EC2 and RDS containers receive a private IP from their subnet's CIDR range and Docker binds the container to that exact address. When disabled, Docker assigns the container address automatically and the recorded private IP is updated to match it. Default: on - without this, two instances in different subnets of the same VPC both land on whatever Docker's IPAM picks (e.g. 10.0.... |
RUNTIME_COMPONENTS core | (unset) | loaded components name - default: all components are loaded and the first one is chosen |
USE_SSL core | 0 | whether to assume http or https for `get_protocol` |
VOLUME_DIR core | (unset) | this is exclusively for the CLI to configure the container mount into /var/lib/localemu |
WAIT_FOR_DEBUGGER core | 0 | whether to make debugpy wait for a debbuger client |
CONTAINER_RUNTIME docker | (unset) | The default container runtime to use |
DOCKER_BRIDGE_IP docker | (unset) | IP of the docker bridge used to enable access between containers |
DOCKER_CMD docker | (unset) | command used to run Docker containers (e.g., set to "sudo docker" to run as sudo) |
DOCKER_FLAGS docker | (unset) | additional flags to pass to "docker run" when starting the stack in Docker |
DOCKER_GLOBAL_IMAGE_PREFIX docker | (unset) | global prefix to prepend to Docker image names (e.g., for using a custom registry mirror) |
DOCKER_SDK_DEFAULT_RETRIES docker | (unset) | Default number of retries to connect to the Docker API by the Docker SDK client. |
DOCKER_SDK_DEFAULT_TIMEOUT_SECONDS docker | (unset) | Default timeout for Docker API calls sent by the Docker SDK client, in seconds. |
DOCKER_SOCK docker | (unset) | path to local Docker UNIX domain socket |
MAIN_DOCKER_NETWORK docker | (unset) | TODO remove fallback to LAMBDA_DOCKER_NETWORK with next minor version |
DYNAMODB_ERROR_PROBABILITY dynamodb | (unset) | randomly inject faults to DynamoDB |
DYNAMODB_REMOVE_EXPIRED_ITEMS dynamodb | 0 | Enables the automatic removal of stale KV pairs based on TTL. |
KINESIS_ERROR_PROBABILITY kinesis | (unset) | Kinesis fault injection. |
LAMBDA_DEBUG_MODE_CONFIG_PATH lambda | (unset) | path to the lambda debug mode configuration file. |
LAMBDA_LIMITS_TOTAL_CODE_SIZE lambda | 80_530_636_800 | SEMI-PUBLIC: not actively communicated |
LAMBDA_RETRY_BASE_DELAY_SECONDS lambda | (unset) | INTERNAL: 60 (default matching AWS) only applies to new lambda provider Base delay in seconds for async retries. Further retries use: NUM_ATTEMPTS * LAMBDA_RETRY_BASE_DELAY_SECONDS 300 (5min) is the maximum because NUM_ATTEMPTS can be at most 3 and SQS has a message timer limit of 15 min. For example: 1x LAMBDA_RETRY_BASE_DELAY_SECONDS: delay between initial invocation and first retry 2x LAMBDA... |
OPENSEARCH_CUSTOM_BACKEND opensearch | (unset) | URL to a custom OpenSearch/Elasticsearch backend cluster. If this is set to a valid URL, then localemu will not create OpenSearch/Elasticsearch cluster instances, but instead forward all domains to the given backend. |
OPENSEARCH_MULTI_CLUSTER opensearch | 1 | Whether to start one cluster per domain (default), or multiplex opensearch domains to a single clusters |
CLEAR_TMP_FOLDER other | 1 | whether to clear config.dirs.tmp on startup and shutdown |
DISTRIBUTED_MODE other | 0 | (no description in config.py - see source) |
EAGER_SERVICE_LOADING other | 0 | whether to eagerly start services |
ENABLE_CONFIG_UPDATES other | 0 | whether to enable API-based updates of configuration variables at runtime |
EXTRA_CORS_ALLOWED_HEADERS other | (unset) | (no description in config.py - see source) |
EXTRA_CORS_ALLOWED_ORIGINS other | (unset) | (no description in config.py - see source) |
EXTRA_CORS_EXPOSE_HEADERS other | (unset) | (no description in config.py - see source) |
FAIL_FAST other | 0 | Whether to report internal failures as 500 or 501 errors. |
FORCE_SHUTDOWN other | 1 | whether to skip waiting for the infrastructure to shut down, or exit immediately |
INCLUDE_STACK_TRACES_IN_HTTP_RESPONSE other | 0 | environment variable to determine whether to include stack traces in http responses |
INTERNAL_RESOURCE_ACCOUNT other | (unset) | AWS account used to store internal resources such as Lambda archives or internal SQS queues. It should not be modified by the user, or visible to him, except as through a presigned url with the get-function call. |
IN_MEMORY_CLIENT other | 0 | This flag enables `connect_to` to be in-memory only and not do networking calls |
LEGACY_DOCKER_CLIENT other | 0 | use the command line docker client instead of the new sdk version, might get removed in the future |
LEGACY_SNS_GCM_PUBLISHING other | 0 | Whether to really publish to GCM while using SNS Platform Application (needs credentials) |
MAIN_CONTAINER_NAME other | (unset) | name of the main Docker container |
OPENAPI_VALIDATE_REQUEST other | 0 | Flag to enable the validation of the requests made to the LocalEmu internal endpoints. Active by default. |
OPENAPI_VALIDATE_RESPONSE other | 0 | Feature flag to enable validation of internal endpoint responses in the handler chain. For test use only. |
OUTBOUND_HTTPS_PROXY other | (unset) | Equivalent to HTTPS_PROXY, but only applicable for external connections |
OUTBOUND_HTTP_PROXY other | (unset) | Equivalent to HTTP_PROXY, but only applicable for external connections |
PARITY_AWS_ACCESS_KEY_ID other | 0 | Whether to return and parse access key ids starting with an "A", like on AWS |
PORTS_CHECK_DOCKER_IMAGE other | (unset) | Docker image to use when starting up containers for port checks |
REMOVE_SSL_CERT other | 0 | Whether delete the cached signed SSL certificate at startup |
SKIP_INFRA_DOWNLOADS other | (unset) | Whether to skip downloading additional infrastructure components (e.g., custom Elasticsearch versions) |
SKIP_SSL_CERT_DOWNLOAD other | 0 | Whether to skip downloading our signed SSL cert. |
STRICT_SERVICE_LOADING other | 1 | whether to selectively load services in SERVICES |
TF_COMPAT_MODE other | 0 | whether to run in TF compatibility mode for TF integration tests (e.g., returning verbatim ports for ELB resources, rather than edge port 4566, etc.) |
THROTTLE_RATE other | 0.05 | probability (0.0–1.0) that a request is throttled when simulation is enabled |
WINDOWS_DOCKER_MOUNT_PREFIX other | /host_mnt | path prefix for windows volume mounting |
PERSISTENCE persistence | 0 | whether localemu should persist service state across localemu runs |
SNAPSHOT_FLUSH_INTERVAL persistence | (unset) | the flush interval (in seconds) for persistence when the snapshot save strategy is set to "scheduled" |
SNAPSHOT_LOAD_STRATEGY persistence | (unset) | the strategy for loading snapshots from disk when `PERSISTENCE=1` is used (on_startup, on_request, manual) |
SNAPSHOT_SAVE_STRATEGY persistence | (unset) | the strategy saving snapshots to disk when `PERSISTENCE=1` is used (on_shutdown, on_request, scheduled, manual) |
STATE_SERIALIZATION_BACKEND persistence | (unset) | Serialization backend for the LocalEmu internal state (`dill` is used by default`). |
S3_SKIP_KMS_KEY_VALIDATION s3 | 1 | whether to skip S3 validation of provided KMS key |
S3_SKIP_SIGNATURE_VALIDATION s3 | 0 | Whether to skip S3 presigned-URL signature validation. The historical default ``is_env_not_false(...)`` returned True when the env var was unset, meaning every freshly-started LocalEmu served tampered presigned URLs without checking the signature - the canonical request could be rewritten by any caller after the URL was minted and the server would still serve it. Real S3 always validates the si... |
SIMULATE_LATENCY simulation | (unset) | Simulate network latency for AWS API responses. Set to "1" or "true" for per-service realistic latency profiles, or a number for fixed ms delay. |
SIMULATE_THROTTLING simulation | 0 | whether to simulate AWS API throttling (off by default) |
SNS_CERT_URL_HOST sns | (unset) | (no description in config.py - see source) |
SNS_PROVIDER_V2 sns | (unset) | (no description in config.py - see source) |
SNS_SES_SENDER_ADDRESS sns | (unset) | (no description in config.py - see source) |
SQS_DELAY_PURGE_RETRY sqs | 0 | Used to toggle PurgeInProgress exceptions when calling purge within 60 seconds |
SQS_DELAY_RECENTLY_DELETED sqs | 0 | Used to toggle QueueDeletedRecently errors when re-creating a queue within 60 seconds of deleting it |
SQS_DISABLE_CLOUDWATCH_METRICS sqs | 0 | Disable cloudwatch metrics for SQS |
SQS_DISABLE_MAX_NUMBER_OF_MESSAGE_LIMIT sqs | 0 | Disable the check for MaxNumberOfMessage in SQS ReceiveMessage |
SQS_ENABLE_MESSAGE_RETENTION_PERIOD sqs | 0 | Used to toggle MessageRetentionPeriod functionality in SQS queues |
SQS_ENDPOINT_STRATEGY sqs | (unset) | Strategy used when creating SQS queue urls. can be "off", "standard" (default), "domain", "path", or "dynamic" |
SFN_MOCK_CONFIG stepfunctions | (unset) | Specifies the path to the mock configuration file for Step Functions, commonly named MockConfigFile.json. |
Common patterns
A few combinations come up over and over:
Persistent local dev with Docker-backed services on:
PERSISTENCE=1 \
EC2_VM_MANAGER=docker \
RDS_DOCKER_BACKEND=1 \
ECS_DOCKER_BACKEND=1 \
EKS_K8S_PROVIDER=k3d \
localemu startStrict IAM enforcement (production-mirror):
IAM_ENFORCEMENT=1 \
ROOT_ACCESS_KEYS=AKIAIOSFODNN7EXAMPLE \
localemu startMimic real AWS quirks (cold starts, throttling, latency):
LAMBDA_COLD_START_DELAY=3 \
SIMULATE_THROTTLING=1 \
SIMULATE_LATENCY=1 \
localemu start