MiniStack stands out by offering a local AWS emulator that runs over 40 AWS services on a single port with a remarkably small footprint and startup time. Unlike many mock-based emulators, it runs real infrastructure components, making it a practical tool for developers and CI environments wanting realistic AWS service behavior locally.
what ministack does and how it works
MiniStack is an open-source, MIT-licensed project that emulates a broad swath of AWS services locally. It bundles these services behind a single HTTP/2-enabled port (4566), exposing a consistent API compatible with real AWS endpoints. This means you can use AWS SDKs like boto3, CLI tools, Terraform, CDK, and Pulumi against MiniStack as if you were talking to the actual AWS cloud.
Under the hood, MiniStack avoids the usual shortcut of mocking service APIs. Instead, it runs actual infrastructure components inside containers: Postgres and MySQL for RDS, Redis for ElastiCache, DuckDB for Athena’s SQL engine, and Docker containers for ECS and Lambda executions. This approach gives you much closer behavior to production AWS, including real SQL dialects, caching semantics, and container lifecycles.
The project emphasizes a tiny resource footprint: a ~270MB Docker image and ~21MB RAM at idle, which is much lighter than LocalStack’s roughly 1GB image and 500MB RAM. Startup times are under 2 seconds, making it suitable for quick iterative development or CI pipeline tasks.
A key architectural highlight is that MiniStack runs all emulated services on a single port, simplifying networking and firewall configurations. It also supports HTTP/2, which can improve client performance.
the multi-tenancy model that sets ministack apart
What really distinguishes MiniStack is its multi-tenancy implementation. Instead of requiring separate MiniStack instances or complex namespace configurations, MiniStack parses the AWS_ACCESS_KEY_ID environment variable. If this ID is a 12-digit number, MiniStack treats it as the AWS Account ID for that session.
This means each developer, CI job, or team member can set a unique 12-digit AWS_ACCESS_KEY_ID and get completely isolated AWS resources — S3 buckets, SQS queues, Lambdas, DynamoDB tables, and more — without any additional configuration or setup.
This design cleverly uses existing AWS SDK behavior and ARN formats to segregate resources. It’s zero overhead and requires no tenant management UI, no separate server instances, and no complex network isolation.
The tradeoff here is that the isolation is logical within MiniStack’s state management, not enforced by separate container sandboxes per tenant. For most local dev and testing workflows, this is sufficient and much easier to operate.
The code quality reflects this pragmatic approach: the repo is well organized, emphasizing simplicity and performance. The use of real containers adds some complexity but improves fidelity.
quick start with ministack
To get started with MiniStack, you can run it directly from Docker Hub with these commands:
# Run MiniStack with the default AWS service emulation
docker run -p 4566:4566 ministackorg/ministack
# Run MiniStack with real infrastructure services (RDS, ECS, Lambda containers)
docker run -p 4566:4566 -v /var/run/docker.sock:/var/run/docker.sock ministackorg/ministack
The second command mounts the Docker socket, enabling MiniStack to spin up real Postgres, MySQL, Redis, and Lambda containers instead of mocks.
For Lambda functions, you can configure LAMBDA_EXECUTOR=docker to run Lambda invocations inside real AWS runtime containers pulled from public AWS ECR images. This improves compatibility with AWS Lambda environments.
Networking nuances include setting DOCKER_NETWORK when running MiniStack inside Docker Compose to ensure Lambda and other container-backed services can communicate correctly.
The commands and environment variables are well documented in the README, making it straightforward to tailor MiniStack for local development or CI.
verdict: who should consider ministack
MiniStack is a solid choice for developers and teams who need a local AWS emulator that balances realism, speed, and resource efficiency.
Its biggest strength is running real infrastructure components rather than mocks, which means fewer surprises when moving from local development to production. Its multi-tenancy model is a practical solution for shared environments, especially in CI pipelines or multi-developer setups.
That said, MiniStack is not a full AWS replacement and may not support every edge case or latest AWS feature. The single-port architecture and containerized backend impose some constraints that might not fit every production-like simulation need.
If you’re looking for a lightweight, fast, and more accurate AWS emulator that you can drop into your development or CI workflow without complex setup, MiniStack is worth trying. The tradeoff is you give up some of the extensive AWS features and ecosystem integrations that heavier emulators or cloud sandboxes might provide.
Overall, MiniStack solves a real problem with a clean, opinionated, and well-engineered approach that stands apart from LocalStack’s heavier and partly commercial solution.
Related Articles
- Traefik: dynamic reverse proxy and load balancer for microservices — Traefik is a Go-based reverse proxy and load balancer that automatically configures routes by integrating with orchestra
- Supabase: composable open-source backend-as-a-service built around Postgres — Supabase combines specialized open-source tools around Postgres to offer a Firebase-like backend platform. Its modular a
- etcd: a robust distributed key-value store built on Go and Raft — etcd is a distributed key-value store in Go that uses the Raft consensus algorithm for high availability and consistency
- Vaultwarden: a resource-efficient Rust implementation of the Bitwarden server API — Vaultwarden is a lightweight, Rust-based server compatible with the Bitwarden API, optimized for self-hosting with low r
- Dokku: A lightweight, Docker-powered mini-Heroku for self-hosting applications — Dokku offers a simple, Docker-based PaaS that lets you deploy apps via Git push on a single server. Ideal for self-hosti
→ GitHub Repo: ministackorg/ministack ⭐ 2,573 · Python