Docs / Configuration

Configuration

LocalEmu is configured through environment variables. Set them before starting, or pass them with docker run -e. The table below covers the core knobs; the per-service Docker backends (RDS_DOCKER_BACKEND, EC2_VM_MANAGER, ECS_DOCKER_BACKEND, MQ_DOCKER_BACKEND, MSK_DOCKER_BACKEND, EKS_K8S_PROVIDER, ...) and simulation switches live in Environment Variables.

Environment Variables

Variable	Default	Description
`GATEWAY_LISTEN`	`0.0.0.0:4566`	Address and port that the gateway listens on. Change the port here to run on a non-default port.
`PERSISTENCE`	`0`	Set to `1` to persist data across restarts. Data is stored in `/var/lib/localemu` (or the configured volume).
`DEBUG`	`0`	Set to `1` to enable verbose debug logging. Useful for troubleshooting service issues.
`SERVICES`	`(all)`	Comma-separated list of services to start. When unset, all services are available. Example: `s3,sqs,dynamodb,lambda`
`LAMBDA_DOCKER_NETWORK`	`bridge`	Docker network for Lambda containers. Set this to your Compose network name so Lambda functions can reach LocalEmu and other containers.
`LAMBDA_RUNTIME_EXECUTOR`	`docker`	Lambda invocation backend. Currently the only registered executor is `docker` (each invocation runs in its own container, reused while warm). The old `LAMBDA_EXECUTOR` name is deprecated.
`LOCALEMU_HOST`	`localhost`	Hostname that LocalEmu uses when constructing URLs (e.g., in SQS queue URLs). Set to the container name in Docker Compose.
`DATA_DIR`	`(auto)`	Legacy, inherited from the upstream codebase. Prefer `PERSISTENCE=1`, which picks a platform-appropriate directory automatically. `DATA_DIR` still works if you need to pin a specific path.
`LOCALEMU_ENDPOINT`	`http://localhost:4566`	Endpoint used by the `awsemu` CLI. Override this to point at a remote instance or different port.

Examples

Run only specific services

Terminal

$ SERVICES=s3,sqs,dynamodb localemu start
Starting services: s3, sqs, dynamodb
Ready.

Enable persistence

Terminal

$ PERSISTENCE=1 localemu start
Persistence enabled. Data directory: /var/lib/localemu
Ready.

Run on a custom port

Terminal

$ GATEWAY_LISTEN=0.0.0.0:5000 localemu start
Listening on 0.0.0.0:5000
Ready.

# Then use awsemu with the custom endpoint
$ LOCALEMU_ENDPOINT=http://localhost:5000 awsemu s3 ls

Debug mode

Terminal

$ DEBUG=1 localemu start
Debug logging enabled.
Ready.

Docker with all options

Terminal

$ docker run -d \
    --name localemu \
    -p 4566:4566 \
    -e PERSISTENCE=1 \
    -e DEBUG=1 \
    -e SERVICES=s3,sqs,dynamodb,lambda \
    -e LAMBDA_DOCKER_NETWORK=my-network \
    -e LAMBDA_RUNTIME_EXECUTOR=docker-reuse \
    -v localemu-data:/var/lib/localemu \
    -v /var/run/docker.sock:/var/run/docker.sock \
    localemu/localemu:latest

Persistence

By default, LocalEmu is ephemeral: all service state is lost when the process stops. Setting PERSISTENCE=1 saves all service state to disk so your data survives restarts.

How to enable

Terminal

$ PERSISTENCE=1 localemu start
Persistence enabled. Data directory: /var/lib/localemu
Ready.

Where data is stored

Persistent state is written to ~/.localemu/state/ on the host (or /var/lib/localemu inside the Docker container). The path is picked automatically. DATA_DIR is supported as a legacy override if you need to pin a specific path.

What is persisted

Everything. When persistence is enabled, LocalEmu saves the full state of every service, including:

• S3 buckets and objects
• DynamoDB tables and items
• SQS queues and in-flight messages
• Secrets Manager secrets
• Lambda function configurations and code
• IAM users, roles, and policies
• SNS topics, SES identities, KMS keys, and all other service resources

Snapshot strategies

You can create manual snapshots of your LocalEmu state for backup or sharing. The simplest approach:

Terminal

# 1. Stop LocalEmu to flush all state to disk
$ localemu stop

# 2. Copy the state directory
$ cp -r ~/.localemu/state/ ~/my-snapshot/

# 3. Restart
$ PERSISTENCE=1 localemu start

# To restore a snapshot later, stop and replace the state directory:
$ localemu stop
$ rm -rf ~/.localemu/state/
$ cp -r ~/my-snapshot/ ~/.localemu/state/
$ PERSISTENCE=1 localemu start

No paid plan, no external server, no Cloud Pods. Just files on your disk.

← Docker CLI Commands →