Environment Variables
Complete reference for the 115 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 (2)
Preview features that may change between releases.
| Variable | Default | Description |
|---|---|---|
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) (85)
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 |
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. |
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. |
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. |
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`). |
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