LocalEmu vs Real AWS
A side-by-side comparison of what behaves identically, what differs, and strategies to bridge the gaps.
The basics
localhost:4566IAM_ENFORCEMENT=1 for real checks)PERSISTENCE=1 for durable)localemu start (~2 seconds)What behaves identically
API contract
Same operations, same parameters, same response shapes. Your code talks to LocalEmu exactly the way it talks to AWS.
Error codes
Same error types for the same conditions. If AWS returns ResourceNotFoundException, LocalEmu returns it too.
IAM evaluation logic
When IAM_ENFORCEMENT=1 is enabled, LocalEmu uses the same algorithm for identity policies, resource policies, and permission boundaries. Service Control Policies (Organizations / SCPs) are not implemented: see Known Limitations.
S3
Same bucket and object operations, versioning, lifecycle rules. Your S3 code works unchanged.
DynamoDB
Same query and scan semantics, GSI/LSI, conditional writes. Your DynamoDB access patterns work identically.
SQS
Same message semantics, visibility timeouts, dead letter queues. Your queue consumers behave the same way.
Lambda
Same invocation model, environment variables, layers. Your functions execute with the same interface.
What differs
Performance
Real AWS has real network latency. LocalEmu responds in <1ms by default. Use SIMULATE_LATENCY=1 to add realistic delays.
Throttling
Real AWS rate-limits. LocalEmu does not by default. Use SIMULATE_THROTTLING=1 to test retry logic.
Lambda cold starts
Real AWS has real cold starts (100ms–10s). LocalEmu is instant by default. Use LAMBDA_COLD_START_DELAY=3 to simulate.
Eventual consistency
S3 is now strongly consistent on AWS (since Dec 2020). LocalEmu is also strongly consistent. But some services (IAM policy propagation, DynamoDB global tables) have eventual consistency on AWS that LocalEmu does not replicate.
Resource limits
AWS enforces service quotas (e.g., 1,000 S3 buckets per account, 500 Lambda concurrent executions). LocalEmu does not enforce these limits.
Managed service internals
RDS runs real PostgreSQL/MySQL (with RDS_DOCKER_BACKEND=1), but does not have automated backups, multi-AZ, or read replicas. ECS runs real containers (with ECS_DOCKER_BACKEND=1), but does not have Fargate or ELB integration.
Bridging the gap
Develop locally with LocalEmu
Fast feedback, zero cost. Write code, run it, see the result in under a second.
Enable simulation flags for realistic testing
Turn on IAM_ENFORCEMENT=1, SIMULATE_LATENCY=1, and SIMULATE_THROTTLING=1 to catch issues before they reach AWS.
Run integration tests against LocalEmu in CI
Your CI pipeline starts LocalEmu, runs your test suite, and tears down. No AWS credentials needed in CI.
Run smoke tests against real AWS in staging
A small set of critical-path tests against your staging environment validates the real AWS behavior.
Deploy to production with confidence
You tested locally, tested with simulation flags, tested in CI, and validated in staging. You are ready.
When to use real AWS
LocalEmu covers the vast majority of development and testing workflows. But there are scenarios where real AWS is the right choice.
- • Performance benchmarking. Real latency numbers can only come from real infrastructure.
- • Load testing at production scale. LocalEmu runs on your machine. It cannot replicate the throughput of a globally distributed cloud.
- • Testing managed service-specific features. RDS automated backups, CloudFront edge caching, Route 53 health checks, and similar features that depend on AWS infrastructure.
- • Final pre-production validation. Before a major release, a smoke test against real AWS in a staging environment gives you the last layer of confidence.