MiniStack: Run 42 AWS Services Locally for Free — The LocalStack Alternative That Doesn't Lock You Out

LocalStack used to be the go-to tool for running AWS locally during development. Then they moved core services behind a paid plan, and a lot of teams suddenly needed an alternative.

MiniStack fills that gap. It’s MIT-licensed, free forever, runs 42 AWS services on a single port, starts in under 2 seconds, and requires no account, no API key, no sign-up. It’s a drop-in replacement — same port (4566), works with boto3, AWS CLI, Terraform, CDK, Pulumi, and any AWS SDK.

# That's the entire setup
docker run -p 4566:4566 ministackorg/ministack

What LocalStack Changed (and Why It Matters)

LocalStack Community edition was free and open source — the version developers relied on for local S3, Lambda, DynamoDB, SQS, and basic CI testing. The paid tier existed but most teams didn’t need it.

When they moved services behind the pro plan, teams running open-source CI pipelines or budget-constrained projects had a real problem. The free tier became genuinely limited for serious development work.

MiniStack was built explicitly as the response. Same port, same SDK compatibility, proper open-source license with no bait-and-switch.

What’s Actually Emulated

42 services on port 4566. The core ones that matter for most projects:

Compute & Eventing

• Lambda — Python and Node.js run with a warm worker pool (fast). Go, Rust, C++ run via Docker RIE. Real execution, not mocked responses.
• Step Functions — full ASL interpreter with Retry/Catch, Map/Parallel, waitForTaskToken, and a TestState API for testing individual states in isolation
• EventBridge — rules, targets, Lambda dispatch on PutEvents, S3 notifications
• SQS / SNS — FIFO queues with deduplication, DLQ support, SNS→SQS and SNS→Lambda fanout

Storage

• S3 — full CRUD, multipart uploads, versioning, lifecycle, CORS, bucket policies, Object Lock with retention enforcement. Optional disk persistence via S3_PERSIST=1
• DynamoDB — full query/scan/transactions, TTL enforced via background reaper, DynamoDB Streams
• Secrets Manager, SSM Parameter Store — full CRUD, SecureString support

Networking & APIs

• API Gateway v1 and v2 — REST and HTTP APIs, Lambda proxy integration, live traffic routing
• ELBv2 / ALB — path-pattern routing, Lambda targets, live traffic
• CloudFront — distributions, invalidations, Origin Access Control

Real Infrastructure (not mocks)

This is where MiniStack separates itself. Several services spin up actual Docker containers:

• RDS — CreateDBInstance starts a real Postgres or MySQL container and returns an actual connection endpoint. You can connect with psycopg2 or pymysql directly.
• ElastiCache — CreateCacheCluster starts a real Redis or Memcached container
• ECS — RunTask pulls images and starts real Docker containers via the Docker socket
• Athena — queries execute real SQL via DuckDB, not mock responses

import boto3, psycopg2

rds = boto3.client("rds", endpoint_url="http://localhost:4566",
    aws_access_key_id="test", aws_secret_access_key="test", region_name="us-east-1")

resp = rds.create_db_instance(
    DBInstanceIdentifier="mydb",
    DBInstanceClass="db.t3.micro",
    Engine="postgres",
    MasterUsername="admin",
    MasterUserPassword="password",
    DBName="appdb",
    AllocatedStorage=20,
)

endpoint = resp["DBInstance"]["Endpoint"]

# This is a real Postgres instance — connect directly
conn = psycopg2.connect(
    host=endpoint["Address"],
    port=endpoint["Port"],
    user="admin", password="password", dbname="appdb"
)

IAM, STS, KMS, Cognito, ECR, CloudFormation — all included. CloudFormation supports 70+ resource types with real intrinsic functions, change sets, and rollback.

Size and Speed

	MiniStack	LocalStack Community
Image size	~270MB	~1GB
RAM at idle	~45MB	~500MB
Startup time	< 2 seconds	10–30 seconds
License	MIT	Apache 2.0 (limited free tier)
Services free	42	Restricted

The footprint difference matters in CI. A 270MB image that starts in 2 seconds is a very different CI experience than a 1GB image with a 30-second warm-up — especially when you’re running dozens of pipelines a day.

Drop-In Compatibility

The migration from LocalStack is minimal. If you were using --endpoint-url http://localhost:4566, you’re done. MiniStack also responds to LocalStack’s health endpoint paths (/_localstack/health, /health) for compatibility with existing tooling.

# AWS CLI — same as before
export AWS_ACCESS_KEY_ID=test
export AWS_SECRET_ACCESS_KEY=test
export AWS_DEFAULT_REGION=us-east-1

aws --endpoint-url=http://localhost:4566 s3 mb s3://my-bucket
aws --endpoint-url=http://localhost:4566 dynamodb list-tables
aws --endpoint-url=http://localhost:4566 lambda list-functions

Terraform works too — point the AWS provider at http://localhost:4566:

provider "aws" {
  access_key = "test"
  secret_key = "test"
  region     = "us-east-1"

  endpoints {
    s3       = "http://localhost:4566"
    dynamodb = "http://localhost:4566"
    lambda   = "http://localhost:4566"
    sqs      = "http://localhost:4566"
  }
}

Multi-Tenancy for Teams

A neat feature for shared environments: if your AWS_ACCESS_KEY_ID is a 12-digit number, MiniStack uses it as the account ID. Resources are fully isolated per account — same instance, different tenants.

# Developer A
export AWS_ACCESS_KEY_ID=111111111111
aws --endpoint-url=http://localhost:4566 s3 mb s3://dev-a-bucket

# Developer B — completely isolated, same MiniStack instance
export AWS_ACCESS_KEY_ID=222222222222
aws --endpoint-url=http://localhost:4566 s3 ls  # sees nothing from dev A

This makes it practical to run a single shared MiniStack in a dev environment with per-developer isolation — no extra setup, no config files.

CI Pipeline Integration

This is the strongest use case. A typical GitHub Actions setup:

services:
  ministack:
    image: ministackorg/ministack
    ports:
      - 4566:4566
    options: >-
      --health-cmd "curl -f http://localhost:4566/_ministack/health"
      --health-interval 2s
      --health-timeout 3s
      --health-retries 5

steps:
  - name: Run tests
    env:
      AWS_ACCESS_KEY_ID: test
      AWS_SECRET_ACCESS_KEY: test
      AWS_DEFAULT_REGION: us-east-1
      AWS_ENDPOINT_URL: http://localhost:4566
    run: pytest tests/

The reset endpoint is particularly useful for test isolation between runs:

# Call this in setUp/beforeEach — wipes all state instantly
curl -X POST http://localhost:4566/_ministack/reset

No container restart needed. Clean state in milliseconds.

What It Doesn’t Do

Worth being clear: MiniStack is a development emulator, not a production cloud platform.

• EC2 is in-memory only — no real VMs spin up. Instance metadata exists but there’s no actual compute
• State is ephemeral by default — restarts wipe everything (except S3 with S3_PERSIST=1)
• No SLAs, no ops, no billing — it’s a local test harness, not infrastructure you’d serve production traffic on
• API parity isn’t perfect — edge cases in complex services (advanced Step Functions, CloudFormation drift detection, etc.) may behave differently from real AWS

The right framing: test your AWS infrastructure code locally before deploying to real AWS. Don’t run client workloads on it.

Getting Started

# Simplest — PyPI
pip install ministack && ministack

# Docker
docker run -p 4566:4566 ministackorg/ministack

# With real infrastructure (RDS, ECS, Lambda containers)
docker run -p 4566:4566 \
  -v /var/run/docker.sock:/var/run/docker.sock \
  ministackorg/ministack

# docker-compose
git clone https://github.com/ministackorg/ministack
cd ministack && docker compose up -d

# Verify
curl http://localhost:4566/_ministack/health

Mount the Docker socket if you need real RDS, ElastiCache, or ECS containers — that’s what lets MiniStack spin up actual Postgres/Redis/Docker workloads on your machine.

---

LocalStack’s pricing shift created a real gap for teams that need AWS compatibility without the infrastructure cost or sign-up friction. MiniStack is a serious answer — MIT licensed, production-provenance quality, and light enough to run anywhere from a laptop to a GitHub Actions runner.

MiniStack → github.com/ministackorg/ministack
Website → ministack.org · MIT License · Free forever