Configuration

CLI flags and environment variables for fakecloud.

fakecloud is configured via CLI flags or environment variables. Flags take precedence when both are set.

FlagEnv VarDefaultDescription
--addrFAKECLOUD_ADDR0.0.0.0:4566Listen address and port
--regionFAKECLOUD_REGIONus-east-1AWS region to advertise
--account-idFAKECLOUD_ACCOUNT_ID123456789012AWS account ID
--log-levelFAKECLOUD_LOGinfoLog level (trace, debug, info, warn, error)
--storage-modeFAKECLOUD_STORAGE_MODEmemorymemory (default, all state in RAM) or persistent (mirror state to --data-path)
--data-pathFAKECLOUD_DATA_PATH—Directory to persist state to. Required when --storage-mode=persistent.
--s3-cache-sizeFAKECLOUD_S3_CACHE_SIZE268435456In-memory LRU cache for S3 object bodies in persistent mode. Default 256 MiB.
FAKECLOUD_CONTAINER_CLIauto-detectContainer CLI to use (docker or podman)
FAKECLOUD_CONTAINER_BACKENDunset (docker)Global execution backend for all container-backed services (Lambda, ECS, RDS, ElastiCache, EC2). k8s runs them as native Kubernetes Pods. See Kubernetes backend.
FAKECLOUD_LAMBDA_BACKENDinherits globalPer-service override for Lambda (k8s or docker). Wins over FAKECLOUD_CONTAINER_BACKEND.
FAKECLOUD_ECS_BACKENDinherits globalPer-service override for ECS task execution (k8s or docker).
FAKECLOUD_RDS_BACKENDinherits globalPer-service override for RDS DB instances (k8s or docker).
FAKECLOUD_ELASTICACHE_BACKENDinherits globalPer-service override for ElastiCache (k8s or docker).
FAKECLOUD_EC2_BACKENDinherits globalPer-service override for EC2 instances (k8s or docker).
FAKECLOUD_EC2_DEFAULT_IMAGEamazonlinux:2023Base container image EC2 instances boot from (any OS image with tail/sh).
FAKECLOUD_PERSIST_DB_VOLUMESon in persistent modeBack RDS (postgres/mysql/mariadb) data directories with a durable named volume so database contents survive a restart. Defaults on under --storage-mode=persistent, off in memory mode. Set 1/0 to override.
FAKECLOUD_PERSIST_EC2_VOLUMESon in persistent modeBack each EC2 instance's data directory with a durable named volume so its contents survive a restart and stop/start. Defaults on under --storage-mode=persistent, off in memory mode. Set 1/0 to override.
FAKECLOUD_EC2_INSTANCE_DATA_DIR/var/lib/fakecloud/ec2In-instance directory backed by the durable EC2 volume. Point it at wherever your instance workload writes long-lived state.
FAKECLOUD_LAMBDA_MAX_CONCURRENCY10Max warm instances kept per Lambda function. Each instance serves one invocation at a time (the runtime emulator can't handle concurrent events); the pool scales up to this cap under concurrent load, then queues. Raise for higher per-function concurrency.
FAKECLOUD_K8S_NAMESPACEdefaultNamespace fakecloud creates Pods in. Only honored on the K8s backend.
FAKECLOUD_K8S_SELF_URL—In-cluster URL of the fakecloud Service (e.g. http://fakecloud.fakecloud.svc.cluster.local:4566). Required for the K8s backend — Pods fetch artifacts from and call back to this URL.
FAKECLOUD_K8S_ECR_URLhost of _SELF_URLOverride the host:port the K8s backend rewrites AWS private-ECR URIs to. Defaults to the host of FAKECLOUD_K8S_SELF_URL.
FAKECLOUD_K8S_PULL_SECRETunsetName of a kubernetes.io/dockerconfigjson Secret used as imagePullSecrets for Pods pulling private images.
FAKECLOUD_K8S_NODE_SELECTORunsetkey=value,key=value node selector applied to every fakecloud Pod. Per-service override: FAKECLOUD_<SERVICE>_K8S_NODE_SELECTOR (e.g. FAKECLOUD_LAMBDA_K8S_NODE_SELECTOR). See Kubernetes backend.
FAKECLOUD_K8S_TOLERATIONSunsetJSON array of k8s Toleration objects applied to every fakecloud Pod. Per-service override: FAKECLOUD_<SERVICE>_K8S_TOLERATIONS.
FAKECLOUD_K8S_ANNOTATIONSunsetkey=value,key=value annotations added to every fakecloud Pod. Per-service override: FAKECLOUD_<SERVICE>_K8S_ANNOTATIONS.
FAKECLOUD_MAX_REQUEST_BODY_BYTES1073741824Max bytes a buffered request body can absorb before fakecloud returns 413. Default 1 GiB. Streaming routes (S3 PutObject / UploadPart, ECR OCI blob upload PATCH / PUT) bypass this cap entirely — they spool the raw HTTP body to disk instead of buffering it all in RAM. Raise this only when stress-testing buffered requests past 1 GiB.
FAKECLOUD_S3_EAGER_DELIVERYunset (off)Deliver S3 server access logs and inventory reports synchronously. Real S3 delivers both asynchronously (logs are best-effort with minutes-to-hours latency; inventory runs on a daily/weekly schedule), so by default fakecloud does not write these objects into the destination bucket, matching how a quick create/destroy never accumulates them. Set 1 to exercise the delivery paths, after which the destination bucket fills with log/report objects.
FAKECLOUD_CLOUDFRONT_DISABLE_DATAPLANEunset (on)Turn off the in-process CloudFront data plane. When set (1/true/yes), enabled distributions are not served on the main listener and report served: false via /_fakecloud/cloudfront/distributions; the control plane is unaffected. See CloudFront.

Examples

# Bind to localhost only
fakecloud --addr 127.0.0.1:4566

# Verbose logging
fakecloud --log-level debug

# Different region and account
fakecloud --region eu-west-1 --account-id 999999999999

# Persistent storage
fakecloud --storage-mode persistent --data-path /var/lib/fakecloud

Environment-only configuration

FAKECLOUD_LOG=trace fakecloud
FAKECLOUD_REGION=eu-central-1 fakecloud

See also Persistence for details on persistent storage mode.

LocalStack and AWS URL compatibility

fakecloud decodes both LocalStack's *.localhost.localstack.cloud hostname convention and the real AWS *.amazonaws.com hostnames. Persisted URLs from either setup — queue URLs baked into dev scripts, presigned URLs in fixtures, webhook targets in response mocks — replay against fakecloud without rewriting. The following patterns are recognized on the Host header:

Host patternRouted as
<service>.<region>.localhost.localstack.cloud[:port]<service> in <region>
<bucket>.s3.<region>.localhost.localstack.cloud[:port]S3 virtual-hosted-style on <bucket>
<service>.<region>.amazonaws.com<service> in <region>
s3.<region>.amazonaws.comS3 path-style
<bucket>.s3.<region>.amazonaws.comS3 virtual-hosted-style on <bucket>
s3.amazonaws.comS3 path-style, legacy us-east-1 global
<bucket>.s3.amazonaws.comS3 virtual-hosted-style on <bucket>, us-east-1
s3-<region>.amazonaws.comS3 path-style, older dash-separated form
<bucket>.s3-<region>.amazonaws.comS3 virtual-hosted-style, older dash-separated

The DNS wildcard *.localhost.localstack.cloud resolves to 127.0.0.1, so LocalStack-shaped hostnames reach fakecloud unchanged; for AWS-shaped hostnames, point the client at fakecloud's endpoint (or add the names to /etc/hosts) and fakecloud parses the Host header to recover service, region, and (for S3) bucket. SigV4-signed requests still route by credential scope first — the hostname is a secondary signal that takes over when the request is unsigned, uses a non-standard Authorization header, or is being probed with curl.

# Unsigned SQS request — routed to SQS purely by Host header
curl -X POST \
     -H 'Host: sqs.us-east-1.amazonaws.com' \
     -d 'Action=ListQueues&Version=2012-11-05' \
     http://127.0.0.1:4566/

# Virtual-hosted-style S3 GetObject — bucket recovered from Host header
curl -H 'Host: my-bucket.s3.us-east-1.amazonaws.com' \
     http://127.0.0.1:4566/key

# Legacy global S3 endpoint — implicit us-east-1
curl -H 'Host: my-bucket.s3.amazonaws.com' http://127.0.0.1:4566/key

Bucket names with dots (e.g. a.b.c) are supported against every S3 suffix; fakecloud recognizes the .s3.<region> / .s3-<region> / .s3 trailer and treats everything before it as the bucket label.