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_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.

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.