What is MiniStack?

MiniStack is a free, open-source AWS emulator that runs on a developer machine or a CI runner and answers AWS API calls on a single local port, 4566 by default. Applications, the AWS CLI, Terraform, AWS CDK, Pulumi and the AWS SDKs reach it by overriding the endpoint URL, so a test suite can create buckets, queues, tables, functions and databases without an AWS account or network access. The project is maintained by the ministackorg organization on GitHub and documented at ministack.org.

The README lists more than 60 emulated services, from S3, SQS, SNS, DynamoDB, Lambda, IAM and STS to Cognito, API Gateway v1 and v2, EventBridge, Step Functions, CloudFormation, ECS, EKS, Athena, Glue, Bedrock and MSK. Most services run in process as Python handlers with in-memory state. Some start real software when Docker is available: RDS launches PostgreSQL or MySQL containers, ElastiCache launches Redis or Valkey, ECS runs containers, and Athena runs SQL through DuckDB in the full image.

MiniStack is distributed as a PyPI package (pip install ministack, which needs Python above 3.10), as the ministackorg/ministack image on Docker Hub, as a larger full image tag, and as source built with Docker Compose. There is also an official Java Testcontainers module published as org.ministack:testcontainers-ministack. The reviewed release is v1.5.38, published November 5, 2026. It added RDS IAM database authentication for PostgreSQL, Cognito refresh token rotation, a Cognito custom email sender trigger and managed login branding, and fixed Object Lock, EventBridge global endpoint and ALB behavior. Releases appear frequently, so check the changelog for the version you pin.

The source license is MIT. The repository was created in March 2026, which makes this a young project with a fast release cadence. An emulator is a test aid, not a copy of AWS: the project documents per-service limitations, and behavior that matters in production, such as IAM enforcement, quotas and consistency timing, should still be validated against a real account.

Key capabilities

Run with Docker docker run -p 4566:4566 ministackorg/ministack starts the gateway with no account, key or sign-up. Mounting /var/run/docker.sock lets services that need real containers, such as RDS, ECS and container-image Lambda, start them on the host. The default image is described in the README as roughly 270 MB, and startup as under two seconds.
Run with pip pip install ministack followed by ministack starts the same gateway from a Python environment on port 4566. GATEWAY_PORT changes the port, and EDGE_PORT is accepted as a LocalStack-compatible alias.
The full image The full tag uses a Debian base and adds DuckDB for Athena plus psycopg2 and pymysql drivers. It is larger, roughly 360 MB per the README, and reports edition: full on the health endpoint. Athena SQL execution needs this image.
60+ services on one port A request router picks the service from the X-Amz-Target header, the credential scope, the Action parameter, the URL path or the host header, and falls back to S3. Service handlers load lazily. Operation coverage differs by service, so read the per-service notes in the reference before relying on a rarely used call.
Multi-account and multi-region isolation A 12-digit AWS_ACCESS_KEY_ID becomes the account ID, and the SigV4 region scopes state, so several teams or CI jobs can share one endpoint without collisions. Since version 1.4.0 regional services keep separate state per region; the README notes S3 and Aurora DSQL as exceptions that share state across regions in an account.
Real databases and caches RDS creates actual PostgreSQL, MySQL or MariaDB containers starting at host port 15432, and ElastiCache creates Redis, Valkey or Memcached containers. Storage is tmpfs by default, 256 MB for RDS, and RDS_PERSIST=1 switches to Docker volumes. This needs a working Docker socket.
Lambda execution Python and Node.js functions can run as local subprocesses, or in containers with LAMBDA_EXECUTOR=docker. LAMBDA_STRICT=1 forces every invocation through the AWS runtime interface emulator image. Warm containers are reused for 300 seconds by default, and a concurrency cap can simulate throttling.
Athena with real SQL In the full image, Athena queries run through DuckDB, with ATHENA_ENGINE set to auto, duckdb or mock. Glue Data Catalog and Glue jobs are emulated alongside it.
Bedrock against local models Converse and InvokeModel return AWS-shaped responses. Setting MINISTACK_BEDROCK_PROXY_URL to an OpenAI-compatible endpoint such as Ollama, llama.cpp or vLLM translates prompts and returns real completions from that backend.
CloudFormation, Terraform, CDK and Pulumi The documentation includes provider and endpoint examples for Terraform, CDK, Pulumi and Amplify. CloudFormation support is marked partial in the project comparison table, so test each resource type your templates use.
Test automation endpoints /_ministack/health reports service status, /_ministack/reset wipes all state between tests, and ?init=1 re-runs init scripts afterwards. Inspection endpoints expose SES messages, SQS messages and SNS SMS messages. A runtime config endpoint changes some service settings without a restart.
Startup scripts Scripts in boot and ready hook directories run at container start, so a project can seed buckets, queues, VPCs and test data automatically. They pair with the reset endpoint for repeatable test fixtures.
State persistence PERSIST_STATE=1 saves service state to STATE_DIR on shutdown and reloads it on startup, using atomic writes. S3 objects persist separately with S3_PERSIST=1. State files carry a format version, and a file written by a newer format is refused rather than misread.
ECS, EKS and compute with real runtimes ECS tasks run as real Docker containers. EKS can provision a real Kubernetes cluster through k3s. Other options cover EC2 instances backed by a real box and a bring-your-own Lambda proxy container.
TLS and metadata service options USE_SSL=1 serves HTTPS with an auto-generated self-signed certificate or one you supply, and Cognito OIDC discovery then uses it. An EC2 instance metadata endpoint is emulated, with IMDSv2 tokens enforced when MINISTACK_IMDS_V2_REQUIRED=1.
Testcontainers modules The repository contains a Testcontainers directory, and the documentation describes usage for Java, Go, Python and .NET. The Java module is published under org.ministack.
No account, no license key The project states that it needs no license key or sign-in and describes itself as free forever under MIT. Verify network behavior in your own environment before using it in a restricted CI network.

Where MiniStack fits

Local development without an AWS account

Start the container, set dummy credentials and an endpoint URL, then point the SDK or the CLI at http://localhost:4566. Create the resources your application expects through a startup script or infrastructure code, and confirm that each service your code touches appears in the health response before running the app.

Continuous integration test suites

Run MiniStack as a service container in the pipeline, call the reset endpoint in each test's setup, and pin the image tag instead of using latest. Because releases are frequent, a pinned version keeps behavior stable between runs. Add a health-check wait so tests do not start before the gateway answers.

Testing Terraform and CDK changes

Configure the provider endpoints for each service to the local port and apply the plan against the emulator before touching a real account. Check that every resource type in the plan is supported, since CloudFormation coverage is partial and some arguments may be accepted but not enforced. Treat a clean apply as a syntax and wiring check, not as proof of IAM correctness.

Integration tests with real databases

Use RDS or ElastiCache with the Docker socket mounted to test connection strings, migrations and drivers against actual PostgreSQL, MySQL or Redis. Confirm the host and port that the emulator returns are reachable from the test runner, and set the public-endpoint option when clients run outside the container network.

Shared team endpoint

Give each developer or pipeline a 12-digit access key so their accounts stay isolated on one shared endpoint. Check that S3 naming does not collide across regions, since S3 shares state across regions within an account, and decide whether persistence should be on for a long-lived shared instance.

Local Bedrock and AI application tests

Point the Bedrock proxy setting at a local Ollama or vLLM endpoint so Converse calls return real model output without cloud spend. Verify the model identifier mapping and timeouts, and keep prompts that must meet production model behavior in a separate real-account test.

Install

docker run -p 4566:4566 ministackorg/ministack

Reviews of MiniStack

No reviews yet

Be the first to share your experience with MiniStack.

Write a review

Loading review form…

Alternatives to MiniStack

FFlociFloci is a free, open-source local AWS emulator for development, testing and CI that works with AWS SDKs, the AWS CLI, Terraform, CDK and OpenTofu.

TerraformTerraform codifies infrastructure as declarative configuration; versions 1.6.0 and later are source-available under the Business Source License, owned by IBM.

DockerDocker makes Docker Engine (open source), Docker Desktop for macOS, Windows and Linux, the Docker Hub registry, Docker Scout, Hardened Images, Build Cloud and Model Runner. Desktop is free for small businesses and personal use; larger organizations need a paid plan.

Compare MiniStack with these tools →