Forem: Nahuel Nucera

What landed in MiniStack between 1.2.0 and 1.3.30

Nahuel Nucera — Thu, 07 May 2026 16:10:04 +0000

MiniStack 1.3.30 is out — here's what shipped recently

MiniStack is a free, MIT-licensed local AWS emulator. Single binary, 55+ services, runs on your laptop or in CI in under a second. No login, no token, no per-seat fee.

GitHub: https://github.com/ministackorg/ministack
Docs: https://ministack.org/docs/

Highlights since 1.3.20

Step Functions aws-sdk:s3 integrations. arn:aws:states:::aws-sdk:s3:listObjectsV2 and 11 other S3 operations now work as native Step Functions SDK integrations: ListBuckets, CreateBucket, DeleteBucket, HeadBucket, GetBucketVersioning, ListObjectsV2, ListObjects, HeadObject, CopyObject, DeleteObject, GetObjectTagging, PutObjectTagging. REST-JSON output also moved to PascalCase to match the rest of the dispatcher, so ResultSelector: $.Records resolves cleanly on aws-sdk:rdsdata:executeStatement.

EC2 DescribeVpcEndpointServices. Returns the standard catalog of 2 Gateway services (s3, dynamodb) and 17 Interface PrivateLink services with region-templated DNS names. ServiceNames, service-name, and service-type filters supported.

DynamoDB legacy parameters. Expected, KeyConditions, ScanFilter, QueryFilter, and AttributeUpdates all work now. The .NET AWS SDK was silently dropping non-key fields on every UpdateItem because it speaks the legacy attribute API under the hood. Fixed.

ECS Task Metadata V4. Every container started by RunTask now gets ECS_CONTAINER_METADATA_URI_V4 injected. The gateway serves /v4/<token>, /v4/<token>/task, and the /stats endpoints. RunTask also translates privileged, linuxParameters.capabilities.add, pidMode: host, and volumes + mountPoints into Docker bind mounts.

AWS CloudTrail. New service. In-memory audit log, opt in via CLOUDTRAIL_RECORDING=1. Per-account ring buffer with LookupEvents covering all eight LookupAttributes. Full control plane: CreateTrail, DeleteTrail, Get/DescribeTrails, StartLogging/StopLogging with real IsLogging state, Put/GetEventSelectors, tag ops.

AWS Resource Groups. New service, 19 of 23 spec operations. Group CRUD, resource queries, configuration, membership, tagging, account settings.

CloudFormation AWS::CloudFront::KeyValueStore. Create / Update / Delete with Arn, Id, Status exposed via Fn::GetAtt. The CFN engine now routes previously-provisioned resources through a per-type update handler when one is defined.

OpenSearch non-VPC domains. VPCOptions is now omitted on non-VPC domains instead of returning an empty object, which was causing the Terraform AWS provider to misclassify them as VPC-backed and fail with OpenSearch Domain in VPC expected to have null Endpoint value.

API Gateway v1 fixes. GetUsagePlanKey handler added (Terraform's aws_api_gateway_usage_plan_key apply was aborting without it). HTTP_PROXY integrations now do path-parameter substitution from integration.request.path.X = method.request.path.X mappings and forward the query string. UpdateModel handler added.

Step Functions REST-JSON casing. Successful REST-JSON integrations like aws-sdk:rdsdata:executeStatement now expose output keys in PascalCase (Records, NumberOfRecordsUpdated) instead of raw camelCase, matching query and REST-XML dispatchers.

SQS ReceiveMessage honours MessageSystemAttributeNames. Only the deprecated AttributeNames was being read, so AWS SDK v2 (Java, Kotlin) consumers were getting empty Attributes and broken ApproximateReceiveCount-based redelivery detection.

SFN aws-sdk:ec2 security group compatibility. CreateSecurityGroup now maps SDK Description to wire GroupDescription, DescribeSecurityGroups sends EC2-shaped filters (Filter.1.Value.1 instead of member.N), and the XML adapter returns SecurityGroups rather than raw SecurityGroupInfo.

CFN AWS::SNS::Subscription honours RawMessageDelivery. The provisioner was silently defaulting to false even when templates set true, so consumers got SNS-wrapped envelopes instead of raw payloads.

Wire-format parity (what makes the project worth using)

All JSON timestamps are int epoch seconds. Java SDK v2 rejects floats. STS Credentials.Expiration, EventBridge Time, EKS createdAt, CloudTrail EventTime, Backup, Firehose — all converted.
KMS Verify raises KMSInvalidSignatureException on bad signatures instead of returning SignatureValid: false with HTTP 200.
KMS crypto operations return the full key ARN as KeyId, not the bare UUID.
DynamoDB ConditionalCheckFailedException populates Item when ReturnValuesOnConditionCheckFailure="ALL_OLD" is set, on Put/Update/Delete/TransactWriteItems.
EC2 VPCs include cidrBlockAssociationSet (Terraform AWS provider v6 crashes without it).
SQS FIFO DeduplicationScope: messageGroup actually scopes per message group.

Try it

docker run --rm -p 4566:4566 ministackorg/ministack:1.3.30

Or pip:

pip install ministack
ministack

Point AWS CLI / boto3 / Terraform at http://localhost:4566 with any non-empty access key.

GitHub: https://github.com/ministackorg/ministack
Docs: https://ministack.org/docs/
LinkedIn: https://www.linkedin.com/company/ministackorg/
Reddit: https://www.reddit.com/r/ministack/

If something is missing or wrong, open an issue.

What landed in MiniStack between 1.2.0 and 1.3.30

Nahuel Nucera — Thu, 07 May 2026 07:27:11 +0000

If you read the 1.2.0 post, that is where this picks up. About four weeks have gone by and over fifty patch releases. This is a tour of what actually shipped, focused on the parts you can use today.

If you have not seen MiniStack before: it is a single-binary local AWS emulator. One process, 46 services, MIT licensed, runs on your laptop or in CI in under a second. Think LocalStack without the paywall and without the JVM.

GitHub: https://github.com/ministackorg/ministack
Docs: https://ministack.org/docs/

New services

EKS with real k3s (1.2.20). CreateCluster spawns a 75 MB k3s container that gives you a real Kubernetes API. kubectl and Helm work against it. CloudFormation provisioners for AWS::EKS::Cluster and AWS::EKS::Nodegroup are wired in. If Docker is unavailable the cluster still goes ACTIVE with a stub endpoint so the API contract holds in CI.

Transfer Family (1.2.17). 10 operations covering server CRUD, user CRUD, SSH key rotation, and LOGICAL home directory mappings to S3. Contributed by @mjdavidson.

EventBridge Scheduler (1.2.19). The full scheduler API: schedule groups, cascading deletes, name and state filters, plus at(), cron(), and rate() expressions. CFN AWS::Scheduler::Schedule and AWS::Scheduler::ScheduleGroup provisioners included. EventBridge cron() rules also fire automatically now (1.3.25), with a zero-dependency parser that covers the full six-field syntax including L, LW, <n>W, <n>#<k>. Contributed by @hiddengearz.

Resource Groups Tagging API (1.3.2). GetResources, GetTagKeys, GetTagValues across 15 services (S3, Lambda, SQS, SNS, DynamoDB, EventBridge, KMS, ECR, ECS, Glue, Cognito, AppSync, Scheduler, CloudFront, EFS). Contributed by @AdigaAkhil.

Resource Groups (1.3.27). 19 of 23 spec operations: group CRUD, resource queries, configuration, membership, tagging, account settings. Requested by @staranto.

AWS CloudTrail (1.3.27). In-memory audit log with control plane and LookupEvents. Per-account ring buffer, opt-in via CLOUDTRAIL_RECORDING=1. Contributed by @AdigaAkhil.

AppSync Events API (1.3.25). Event API management, channel namespaces, API keys, HTTP publish, and realtime WebSocket on the aws-appsync-event-ws subprotocol. Contributed by @marcin-nowak-scl.

CloudFront KeyValueStore (1.3.25, 1.3.26). Both planes: management plane for Create/Describe/List/Update/Delete with ETag concurrency, and a separate cloudfront-keyvaluestore data plane for GetKey/PutKey/DeleteKey/UpdateKeys. CFN AWS::CloudFront::KeyValueStore provisioner included. Contributed by @davireisvieira.

Lambda

A big stretch of work. Highlights:

RIE-based Docker executor (1.2.20). LAMBDA_EXECUTOR=docker now uses official AWS Lambda Runtime Interface Emulator images for every runtime. Containers stay warm between invocations. Originally contributed by @fzonneveld.

Runtime coverage (1.2.21 and after). The full image map today: python3.8 through python3.14, nodejs14.x through nodejs24.x, java8.al2, java11, java17, java21, java25, dotnet6, dotnet8, dotnet10, ruby3.2, ruby3.3, ruby3.4, plus provided, provided.al2, provided.al2023.

Lambda to CloudWatch Logs (1.3.3). Every invocation now writes START, handler output, END, and REPORT lines to /aws/lambda/{FunctionName} on a per-invocation stream. Metric filters, subscription filters, and alarm chains that needed real Lambda logs work locally now. Applies to every executor.

Async retry and DLQ routing (1.3.3). Invoke(InvocationType=Event) and S3-notification fan-out retry up to MaximumRetryAttempts and route the final failure to the configured DLQ or OnFailure destination (SQS, SNS, or another Lambda) with the AWS-shaped envelope.

Docker-in-Docker (1.2.21). Running MiniStack inside Docker with LAMBDA_EXECUTOR=docker works. Code is copied via docker cp instead of bind-mounted, and Lambda containers are reached via container IP. Reported by @HackJack-101.

Filter criteria during polling (1.3.3). SQS, Kinesis, and DynamoDB Streams pollers evaluate each record against FilterCriteria.Filters and drop non-matching records before invoking. Equality lists, prefix, suffix, anything-but, exists, and numeric content filters are all supported.

Step Functions aws-sdk:* integrations

Resource: arn:aws:states:::aws-sdk:<service>:<op> works against the following services in 1.3.30. The list is the actual contents of the dispatch table in ministack/services/stepfunctions.py:

Query protocol: ec2, sqs, sns, rds, elasticache, iam, sts, cloudwatch
JSON protocol: dynamodb, secretsmanager, states (Step Functions calling itself), logs (CloudWatch Logs), ssm, eventbridge, kinesis, glue, athena, ecs, ecr, kms
REST-JSON protocol: rdsdata
REST-XML protocol: s3 (12 ops added in 1.3.29: ListBuckets, CreateBucket, DeleteBucket, HeadBucket, GetBucketVersioning, ListObjectsV2, ListObjects, HeadObject, CopyObject, DeleteObject, GetObjectTagging, PutObjectTagging)
Lambda: dispatched directly to the local Lambda invoker

REST-JSON output now uses PascalCase to match the query and REST-XML dispatchers (1.3.30, contributed by @jayjanssen), so ResultSelector: $.Records works on aws-sdk:rdsdata:executeStatement results.

CloudFormation

New provisioners since 1.2.0:

AWS::Events::EventBus (1.2.21, contributed by @AdigaAkhil)
AWS::Pipes::Pipe (1.3.2, contributed by @davidtme), with FilterPolicy and FilterPolicyScope on AWS::SNS::Subscription
AWS::Scheduler::Schedule, AWS::Scheduler::ScheduleGroup (1.2.19)
AWS::CodeBuild::Project (1.2.19, contributed by @AdigaAkhil)
AWS::EKS::Cluster, AWS::EKS::Nodegroup (1.2.20)
AWS::CloudFront::KeyValueStore (1.3.26), with the engine now routing previously-provisioned resources through a per-type update handler when one is defined

Infrastructure

Hypercorn ASGI with HTTP/2 h2c (1.3.1). Replaces uvicorn. AWS Java SDK v2 and the Kinesis Client Library work out of the box. Idle RAM dropped from about 21 MB to about 7 MB. Contributed by @AdigaAkhil.

Lazy service imports (1.2.19). Service modules load on first request. Idle RAM dropped from 59 MB to 21 MB before the hypercorn cut, startup time from 1.2 s to 0.5 s. Services you never call cost zero memory.

Per-PR preview Docker images (1.3.2). Every PR (including forks) publishes ministackorg/ministack-preview-build:pr-N-<shortsha>. Reviewers can docker pull the exact build before merge. Contributed by @jgrumboe.

Multi-tenancy correctness

1.3.3 closed eight cross-account leaks where services stored per-tenant data in plain dict or list (CloudWatch metrics and alarm history, ElastiCache events, EventBridge buses, Athena workgroups and data catalogs, SES sent emails, API Gateway v1 stages, deployments, authorizers, and tags). All of them now route through AccountScopedDict, with isolation tests in tests/test_multitenancy.py.

Wire-format fixes worth knowing

All timestamps in JSON responses are int epoch seconds. The Java SDK v2 rejects floats. STS Credentials.Expiration, EventBridge Time, EKS createdAt, Backup, Firehose, CloudTrail timestamps were converted across 1.3.x.
KMS Verify raises KMSInvalidSignatureException on bad signatures instead of returning SignatureValid: false.
KMS crypto operations return the full key ARN as KeyId, not the bare UUID.
DynamoDB ConditionalCheckFailedException populates Item when ReturnValuesOnConditionCheckFailure="ALL_OLD" is set, on Put/Update/Delete/TransactWriteItems.
EC2 VPCs include cidrBlockAssociationSet (Terraform AWS provider v6 crashes without it).
SQS FIFO DeduplicationScope: messageGroup actually scopes per message group.
SQS ReceiveMessage honours MessageSystemAttributeNames. AWS SDK v2 was the only thing reading it (1.3.29, contributed by @joaomena).

Get it

docker run --rm -p 4566:4566 ministackorg/ministack:1.3.30

Or pip:

pip install ministack
ministack

GitHub: https://github.com/ministackorg/ministack
Docs: https://ministack.org/docs/
LinkedIn: https://www.linkedin.com/company/ministackorg/
Reddit: https://www.reddit.com/r/ministack/

If something you need is missing or wrong, open an issue. Most of what is listed above started as one.

MiniStack Now Emulates Amazon EKS — Free, Open-Source AWS Emulator v1.2.20

Nahuel Nucera — Fri, 17 Apr 2026 19:02:33 +0000

EKS Joins the Free AWS Emulator

MiniStack v1.2.20 adds Amazon EKS to its list of emulated AWS services. Create clusters, manage node groups, and hit the EKS API surface — all locally, all free.

If you haven't seen MiniStack before: it's a free, MIT-licensed AWS emulator. 40+ services on a single Docker container, single port (4566). No account, no API key, no telemetry. Drop-in compatible with the AWS CLI, Terraform, CDK, and every AWS SDK.

docker run -p 4566:4566 nahuelnucera/ministack

EKS Emulation in Action

aws --endpoint-url=http://localhost:4566 eks create-cluster \
  --name my-cluster \
  --role-arn arn:aws:iam::123456789012:role/eks-role \
  --resources-vpc-config subnetIds=subnet-1,securityGroupIds=sg-1

aws --endpoint-url=http://localhost:4566 eks describe-cluster \
  --name my-cluster

aws --endpoint-url=http://localhost:4566 eks create-nodegroup \
  --cluster-name my-cluster \
  --nodegroup-name my-nodes \
  --node-role arn:aws:iam::123456789012:role/node-role \
  --subnets subnet-1

Terraform and CDK work without changes — just point your provider endpoint to localhost:4566.

Why This Matters

EKS is one of those services that's painful to test against real AWS. Clusters take 10-15 minutes to provision, cost money even when idle, and are overkill when all you need is to validate your IaC or integration logic.

With MiniStack, your Terraform plans, CDK deploys, and SDK integration tests hit a local EKS API instantly. No cluster spin-up time, no AWS bill.

What MiniStack Emulates (40+ Services)

Not just EKS. The full list keeps growing:

Core (in-memory):
S3, SQS, SNS, DynamoDB, Lambda, IAM, STS, Secrets Manager, CloudWatch Logs, SSM Parameter Store, EventBridge, Kinesis, CloudWatch Metrics, SES, Step Functions, Cognito, API Gateway, CloudFormation, ACM, Route 53, Cloud Map

Infrastructure (real Docker containers):
RDS (real Postgres/MySQL), ElastiCache (real Redis), ECS (real Docker containers), Athena (real SQL via DuckDB), Glue

Compute & Container:
EC2, EKS, ECR, Auto Scaling, ELBv2

Data & Analytics:
Firehose, Redshift, S3 Files

Other:
AppConfig, CodeBuild, Scheduler, Resource Groups Tagging API

How It Compares

	LocalStack Free	LocalStack Pro	MiniStack
EKS	❌	✅ Paid	✅ Free
Core services	Now paid	✅	✅ Free
RDS/ElastiCache/ECS	❌	✅	✅ Real containers
Startup	~30s	~30s	~2s
RAM at idle	~500MB	~500MB	~21MB
Image size	~1GB	~1GB	~270MB
License	BSL	Proprietary	MIT
Price	Paid	$35+/mo	Free forever

Try It

docker run -p 4566:4566 nahuelnucera/ministack

No account. No API key. No telemetry.

GitHub: github.com/ministackorg/ministack
Docker Hub: nahuelnucera/ministack
Website: ministack.org

MIT licensed. PRs welcome.

MiniStack: Free Local AWS Emulator + Testcontainers Module + AWS CLI Built In

Nahuel Nucera — Tue, 14 Apr 2026 10:44:56 +0000

4 releases in a weekend: Testcontainers Java module, AWS CLI bundled, Step Functions intrinsics, RDS Data stubs. Free, open-source, MIT licensed.

TL;DR

We shipped 4 releases this weekend (v1.2.6 through v1.2.9):

org.ministack:testcontainers-ministack:0.1.0 on Maven Central
62 bug fixes found by running 2,490 tests across all 41 services
AWS CLI bundled in the Docker image — init scripts just work
Step Functions intrinsics — 7 new functions (ArrayContains, MathAdd, UUID, etc.)
RDS Data API stubs — test database provisioning without Docker-in-Docker

What is MiniStack?

MiniStack is a free, MIT-licensed local AWS emulator. One Docker image, one port (4566), 41 services. It started as a response to LocalStack moving core services behind a paid plan.

Image size: 269MB (was 242MB before CLI)
Startup time: <2 seconds
Services: S3, DynamoDB, SQS, SNS, Lambda, Step Functions, CloudFormation, EC2, ECS, and 32 more
Docker: ministackorg/ministack
GitHub: ministackorg/ministack

No license keys. No pro tiers. Just run it.

docker run -d -p 4566:4566 ministackorg/ministack

Testcontainers Module

<dependency>
    <groupId>org.ministack</groupId>
    <artifactId>testcontainers-ministack</artifactId>
    <version>0.1.0</version>
    <scope>test</scope>
</dependency>

@Testcontainers
class S3IntegrationTest {

    @Container
    static MiniStackContainer ministack = new MiniStackContainer("ministackorg/ministack:latest");

    @Test
    void shouldCreateBucketAndPutObject() {
        S3Client s3 = S3Client.builder()
                .endpointOverride(ministack.getEndpoint())
                .credentialsProvider(ministack.getCredentialsProvider())
                .region(Region.US_EAST_1)
                .build();

        s3.createBucket(b -> b.bucket("test-bucket"));
        s3.putObject(
                b -> b.bucket("test-bucket").key("hello.txt"),
                RequestBody.fromString("Hello MiniStack!")
        );

        String body = s3.getObjectAsBytes(
                b -> b.bucket("test-bucket").key("hello.txt")
        ).asUtf8String();

        assertEquals("Hello MiniStack!", body);
    }
}

Works with JUnit 5 and Spring Boot's @DynamicPropertySource. The container starts in under 2 seconds.

AWS CLI Bundled (v1.2.9)

The Docker image now ships with AWS CLI v1. Init scripts just work without any credential configuration:

# ready.d/01-create-resources.sh
aws s3 mb s3://my-bucket
aws sqs create-queue --queue-name my-queue

# ready.d/02-seed-data.py
import boto3, os
s3 = boto3.client("s3", endpoint_url=os.environ["AWS_ENDPOINT_URL"])
s3.put_object(Bucket="my-bucket", Key="config.json", Body=b'{"env": "local"}')

Both .sh and .py init scripts are supported. AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_DEFAULT_REGION, and AWS_ENDPOINT_URL are automatically set for init scripts.

The Flea Hunt: 62 Bugs Found and Fixed

We ran what we call a "Flea Hunt" — 2,490 tests across all 41 services using 10 parallel MiniStack instances. Some highlights:

S3 versioning — GetObject by VersionId was returning the wrong version. Delete markers were missing entirely from ListObjectVersions.
Lambda — internal _request_id was leaking into handler events. PublishVersion ARN was missing the :version qualifier.
DynamoDB — Go SDK v2 requires a CRC32 header on every response. Without it, the SDK throws an integrity error before your code sees anything.
Java SDK v2 — time.time() floats in scientific notation broke the timestamp parser across 14 services. Fixed with int(time.time()).
EC2 — TagSpecifications were silently ignored on 11 create operations. DeleteVpc succeeded even with subnets attached.

After the fixes: 1,327 regression tests (1,196 Python + 131 Java), zero failures.

Quick Start

Docker:

docker run -d -p 4566:4566 ministackorg/ministack

Terraform:

provider "aws" {
  endpoints {
    s3       = "http://localhost:4566"
    dynamodb = "http://localhost:4566"
    sqs      = "http://localhost:4566"
  }
  region     = "us-east-1"
  access_key = "test"
  secret_key = "test"
}

How we made Step Functions call any AWS service locally

Nahuel Nucera — Tue, 07 Apr 2026 18:43:25 +0000

If you've used AWS Step Functions, you know the aws-sdk:* integration pattern:

{
  "Type": "Task",
  "Resource": "arn:aws:states:::aws-sdk:dynamodb:PutItem",
  "Parameters": {
    "TableName": "my-table",
    "Item": { "pk": { "S.$": "$.id" } }
  }
}

One line in your state machine, and Step Functions calls DynamoDB directly. No Lambda wrapper needed. AWS recommends this for all new workflows.

The problem? Every local AWS emulator hardcodes service integrations. Want SQS? There's a handler. Want SNS? Another handler. Want SecretsManager? Sorry, not implemented yet.

The generic dispatcher

We added a generic aws-sdk:* task dispatcher to MiniStack. Instead of writing a handler for each service, it routes to whatever service is already emulated:

arn:aws:states:::aws-sdk:secretsmanager:CreateSecret  → SecretsManager handler
arn:aws:states:::aws-sdk:dynamodb:PutItem              → DynamoDB handler  
arn:aws:states:::aws-sdk:ecs:RunTask                   → ECS handler
arn:aws:states:::aws-sdk:kms:Encrypt                   → KMS handler

38 services. All callable from Step Functions. No new code needed per service.

How it works

The dispatcher:

Parses the ARN to extract service name and action
Looks up the service in MiniStack's handler map
Constructs the right headers (X-Amz-Target for JSON services)
Converts PascalCase keys to the format each service expects
Calls the handler and returns the result to the workflow

For JSON-protocol services (DynamoDB, SecretsManager, ECS, KMS, CloudWatch Logs, SSM, EventBridge, Kinesis, Glue, Athena, ECR), it works today. Query and REST protocol services are coming.

What else ships with MiniStack

38 AWS services on a single port
1,047 integration tests
48 CloudFormation resource types — CDK bootstrap + deploy works
Terraform VPC module v6.6.0 fully compatible
Lambda — Python, Node.js, Go/Rust/C++ (Docker), Docker images
Real infrastructure — RDS spins up Postgres, ElastiCache runs Redis, ECS starts Docker containers

Try it

docker run -p 4566:4566 nahuelnucera/ministack

Then run your Step Functions workflow locally:

import boto3

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

# Your workflow can now call any of the 38 services
sfn.create_state_machine(
    name="my-workflow",
    definition='...your ASL with aws-sdk integrations...',
    roleArn="arn:aws:iam::000000000000:role/role",
)

MIT licensed. Free forever. github.com/Nahuel990/ministack

Getting started testing AWS with MiniStack in under 10 minutes

Nahuel Nucera — Sun, 05 Apr 2026 11:10:05 +0000

You don't need an AWS account to test your AWS code.

We just published an AWS Testing 101 guide — a step-by-step tutorial that takes you from zero to testing S3, DynamoDB, SQS, and Lambda on your laptop. No credentials, no cloud costs, no cleanup.

The problem

Every developer who writes AWS code hits this wall:

"I don't want to create resources in a real AWS account just to test"
"My CI pipeline needs AWS but I don't want to pay for it"
"I accidentally left a DynamoDB table running and got billed"

The answer is a local AWS emulator. Run it on your machine, point your SDK at localhost:4566, and your code thinks it's talking to AWS.

The setup

docker run -p 4566:4566 nahuelnucera/ministack

That's it. 35+ AWS services running locally.

What the guide covers

1. S3 — Create buckets and upload files

import boto3

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

s3.create_bucket(Bucket="my-bucket")
s3.put_object(Bucket="my-bucket", Key="hello.txt", Body=b"Hello, local AWS!")

2. DynamoDB — Create tables and query data

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

ddb.create_table(
    TableName="users",
    KeySchema=[{"AttributeName": "userId", "KeyType": "HASH"}],
    AttributeDefinitions=[{"AttributeName": "userId", "AttributeType": "S"}],
    BillingMode="PAY_PER_REQUEST",
)

ddb.put_item(TableName="users", Item={
    "userId": {"S": "user-001"},
    "name": {"S": "Alice"},
})

3. SQS — Send and receive messages

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

queue = sqs.create_queue(QueueName="my-queue")
sqs.send_message(QueueUrl=queue["QueueUrl"], MessageBody="Hello from SQS!")
msgs = sqs.receive_message(QueueUrl=queue["QueueUrl"])
print(msgs["Messages"][0]["Body"])  # Hello from SQS!

4. Lambda — Deploy and invoke functions

import zipfile, io

# Package a function
buf = io.BytesIO()
with zipfile.ZipFile(buf, "w") as zf:
    zf.writestr("index.py", 'def handler(event, ctx): return {"message": "Hello from Lambda!"}\n')

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

lam.create_function(
    FunctionName="my-function",
    Runtime="python3.12",
    Handler="index.handler",
    Role="arn:aws:iam::000000000000:role/fake-role",
    Code={"ZipFile": buf.getvalue()},
)

resp = lam.invoke(FunctionName="my-function")
print(resp["Payload"].read())  # {"message": "Hello from Lambda!"}

Why this matters

No AWS account needed — test on day one
No cost — run thousands of operations for free
No cleanup — stop the container, everything's gone
CI/CD ready — same Docker image in GitHub Actions, GitLab CI, Jenkins
Terraform compatible — point your provider at localhost:4566

The full guide

The complete tutorial with more examples and explanations is at:

👉 ministack.org/getting-started.html

MiniStack is the best alternative to LocalStack, it's open-source, MIT licensed, and free forever: github.com/Nahuel990/ministack

docker run -p 4566:4566 nahuelnucera/ministack

One command. 35+ services. Zero cost.

MiniStack vs Floci vs LocalStack: Honest Performance Benchmark (April 3rd 2026)

Nahuel Nucera — Fri, 03 Apr 2026 19:57:59 +0000

We ran 30 API operations, throughput tests, and service coverage checks against real Docker containers. No cherry-picking. No marketing. Just numbers.

TL;DR

Metric	MiniStack	Floci	LocalStack Free
Services supported	31	20	~15 (rest paywalled)
Image size	211 MB	276 MB	~1 GB
Memory after load	39 MB	56 MB	~500 MB
Startup time	<2s	~3s	~15-30s
Median API latency	4.6 ms	5.2 ms	varies
License	MIT	MIT	BSL (restricted)

Methodology

Fresh docker system prune -af --volumes before each run
Both images pulled from Docker Hub (nahuelnucera/ministack:latest, hectorvent/floci:latest)
Each operation run 5 times, median taken
All tests use boto3 with endpoint_url=http://localhost:{port}
Machine: Apple Silicon M4, 24 GB RAM, Docker Desktop
No warm-up runs — cold container, first request measured

Image Size

nahuelnucera/ministack:latest    211 MB
hectorvent/floci:latest          276 MB
localstack/localstack:latest    ~1.0 GB

MiniStack is 24% smaller than Floci and 5x smaller than LocalStack. MiniStack uses Alpine + Python + Node.js. Floci uses a JVM-based stack.

Startup Time

	First Response
MiniStack	1 ms
Floci	15 ms
LocalStack	15-30 seconds

MiniStack starts instantly. No JVM warm-up, no class loading. The ASGI server is ready before the health check even fires.

API Latency (median of 5 runs, single operation)

S3

Operation	Floci	MiniStack	Difference
CreateBucket	5.9 ms	5.6 ms	-5%
PutObject (1 KB)	6.3 ms	6.4 ms	+2%
PutObject (100 KB)	10.6 ms	7.3 ms	-31%
GetObject	4.8 ms	5.4 ms	+13%
ListObjectsV2	5.5 ms	6.2 ms	+13%

S3 is competitive. Floci edges ahead on small reads. MiniStack is significantly faster on larger writes (100 KB: 31% faster).

SQS

Operation	Floci	MiniStack	Difference
CreateQueue	4.5 ms	4.4 ms	-2%
SendMessage	9.8 ms	8.3 ms	-15%
ReceiveMessage	7.8 ms	6.5 ms	-17%

MiniStack is consistently faster on SQS operations.

DynamoDB

Operation	Floci	MiniStack	Difference
CreateTable	3.7 ms	3.4 ms	-8%
PutItem	3.7 ms	4.2 ms	+14%
GetItem	3.8 ms	4.4 ms	+16%
Query	4.3 ms	5.0 ms	+16%
Scan	4.2 ms	4.6 ms	+10%

Floci wins on DynamoDB read/write operations. This is likely due to Java's optimized JSON parsing for the DynamoDB wire format.

Other Services

Operation	Floci	MiniStack	Difference
SNS CreateTopic	3.9 ms	3.8 ms	-3%
SNS Publish	8.5 ms	8.8 ms	+4%
IAM CreateRole	5.0 ms	5.9 ms	+18%
STS GetCallerIdentity	5.1 ms	4.5 ms	-12%
SSM PutParameter	6.6 ms	4.7 ms	-29%
SSM GetParameter	4.7 ms	5.2 ms	+11%
SecretsManager Create	4.8 ms	4.4 ms	-8%
SecretsManager Get	4.7 ms	4.4 ms	-6%
EventBridge PutRule	5.3 ms	4.7 ms	-11%
EventBridge PutEvents	4.8 ms	5.5 ms	+15%
Kinesis CreateStream	5.6 ms	5.1 ms	-9%
CW PutMetricData	4.9 ms	4.4 ms	-10%
Logs CreateLogGroup	6.5 ms	4.6 ms	-29%
Route53 CreateHostedZone	ERR	4.3 ms	Floci doesn't support Route53

MiniStack is faster on SSM, SecretsManager, CloudWatch, and Logs. Floci is faster on IAM and EventBridge PutEvents. Route53 only works on MiniStack.

Throughput

Test	Floci	MiniStack
SQS SendMessage x500	221 ops/s	233 ops/s

On sustained SQS throughput, MiniStack is 5% faster. Earlier cold-start benchmarks showed Floci ahead, but with warm containers the gap disappears.

Memory Usage

State	Floci	MiniStack
At idle	26 MB	38 MB
After 500+ operations	56 MB	39 MB

Interesting: Floci uses less memory at idle (JVM lazy class loading) but grows to 56 MB after load. MiniStack starts at 38 MB and barely grows. Over time, MiniStack's memory profile is more predictable.

Service Coverage

Service	Floci	MiniStack
S3	YES	YES
SQS	YES	YES
SNS	YES	YES
DynamoDB	YES	YES
Lambda	YES	YES
IAM	YES	YES
STS	YES	YES
SecretsManager	YES	YES
CloudWatch Logs	YES	YES
SSM	YES	YES
EventBridge	YES	YES
Kinesis	YES	YES
CloudWatch Metrics	YES	YES
SES	YES	YES
Step Functions	YES	YES
Cognito	YES	YES
RDS	YES	YES
CloudFormation	YES	YES
ACM	YES	YES
KMS	YES	YES
ECS	NO	YES
ElastiCache	NO	YES
Glue	NO	YES
Athena	NO	YES
Firehose	NO	YES
Route53	NO	YES
EC2/VPC	NO	YES
EMR	NO	YES
ELBv2/ALB	NO	YES
WAF v2	NO	YES
ECR	NO	YES
Total	20	31

MiniStack supports 55% more services. The gap is particularly significant for infrastructure-heavy workloads (ECS, RDS with real Docker, EC2/VPC, Route53, ALB).

Feature Comparison

Feature	MiniStack	Floci	LocalStack Free
Lambda Python execution	YES	YES	YES
Lambda Node.js execution	YES	NO	YES
Lambda warm workers	YES	NO	YES
RDS real Postgres/MySQL	YES	YES	NO (Pro)
ECS real Docker containers	YES	NO	NO (Pro)
ElastiCache real Redis	YES	NO	NO (Pro)
Athena real SQL (DuckDB)	YES	NO	NO (Pro)
CloudFormation	YES (12 types)	YES	YES
Step Functions TestState API	YES	NO	NO
SFN Mock Config (SFN Local compat)	YES	NO	YES
State persistence	YES (20 services)	NO	Partial
S3 disk persistence	YES	YES	YES
Detached mode (`-d` / `--stop`)	YES	NO	NO
Terraform v6 compatible	YES	Partial	YES
AWS SDK v2 chunked encoding	YES	NO	YES
Testcontainers examples	Java, Go, Python	NO	Java
`docker run` one-liner	YES	YES	YES
PyPI installable	YES	NO	YES

What Floci Does Better

Let's be honest about where Floci wins:

DynamoDB read latency — 15-16% faster on GetItem/Query/Scan. Java's JSON processing is well-optimized for DynamoDB's wire format.
Idle memory — 26 MB vs 38 MB at cold start. JVM defers class loading.

What MiniStack Does Better

11 more services — ECS, ElastiCache, Glue, Athena, Route53, EC2, EMR, ALB, WAF, Firehose, ECR.
Real infrastructure — RDS spins up actual Postgres/MySQL. ECS runs real containers. Athena runs real SQL via DuckDB.
Lambda Node.js — warm worker pool for both Python and Node.js.
State persistence — 20 services survive restarts.
Faster on most operations — SSM, SecretsManager, SQS, CloudWatch, Logs are 15-30% faster.
Terraform v6 ready — EC2 stubs, S3 Control routing, DynamoDB WarmThroughput.
Smaller image — 211 MB vs 276 MB (24% smaller).

When to Use What

Use MiniStack if:

You need ECS, Route53, EC2, Glue, Athena, ALB, or any of the 11 extra services
You're migrating from LocalStack and need maximum service coverage
You want state persistence across container restarts
You use Terraform v6
You want Lambda Node.js support

Use Floci if:

You only need the core 20 services
DynamoDB read performance is critical for your test suite
You want the smallest possible idle memory footprint

Use LocalStack Pro if:

You need IAM policy enforcement
You need Lambda container image support
Budget isn't a constraint

Benchmark Reproducibility

All benchmarks can be reproduced with:

docker system prune -af --volumes
docker pull nahuelnucera/ministack:latest
docker pull hectorvent/floci:latest

docker run --rm -d --name ms -p 4568:4566 nahuelnucera/ministack:latest
docker run --rm -d --name fl -p 4567:4566 hectorvent/floci:latest

# Run your own boto3 tests against both ports

Versions Tested

MiniStack: v1.1.27 (April 2026)
Floci: latest (April 2026)
LocalStack: comparison based on published documentation (not benchmarked directly)
boto3: 1.34+
Docker Desktop: latest
Hardware: Apple M4, 24 GB RAM

This benchmark was created by the MiniStack team. We tried to be as fair as possible — if you find any methodology issues, please open an issue on GitHub.

Ministack, the best alternative to Localstack

Nahuel Nucera — Mon, 30 Mar 2026 19:18:13 +0000

We built a free LocalStack alternative — after last week’s changes

Last week, LocalStack moved more core services behind a paywall.

For a lot of teams, that quietly broke something important:

👉 local AWS development that just worked

So we decided to build something about it.

Introducing MiniStack

MiniStack is a free, open-source AWS emulator designed for local development and CI/CD.

It just got featured as Project of the Day on aidigitalcrew.com 🙌

What started small grew fast

30 AWS services
~2s startup time
~30MB RAM at idle
Single port (:4566)
600+ integration tests
MIT licensed (fully free)

The key difference: real infrastructure

MiniStack doesn’t just mock APIs where it matters:

RDS → spins up real Postgres/MySQL containers
ElastiCache → runs real Redis
ECS → starts real Docker containers
Athena → executes real SQL via DuckDB

👉 No fake endpoints. No stubbed responses.

Services that are now paid elsewhere — free here

EC2 (instances, VPCs, networking)
EMR (clusters, steps)
Cognito (user + identity pools)
EBS / EFS
ALB / ELBv2

Same developer experience

If you’ve used LocalStack before, nothing changes:

docker run -p 4566:4566 nahuelnucera/ministack

aws --endpoint-url=http://localhost:4566 s3 mb s3://my-bucket

No account
No API key
No telemetry

Why we built this

This isn’t about competing.

LocalStack is a great product.

But local development tooling should be:

fast
predictable
accessible

Try it

⭐ https://github.com/Nahuel990/ministack
⭐ https://ministack.org

Would love feedback, ideas, or contributions from the community.

MiniStack v1.1.2 — Cognito, EC2, EMR, 656 Tests, and Zero Docker Leaks

Nahuel Nucera — Mon, 30 Mar 2026 04:57:48 +0000

We just shipped MiniStack v1.1.2. This is the biggest release since the initial launch — full Amazon Cognito support, partial EC2, EMR, a complete test suite overhaul, and a pile of infrastructure fixes that make running MiniStack day-to-day significantly cleaner.

If you're not familiar: MiniStack is a free, open-source local AWS emulator. One port, no account, no license key. A drop-in replacement for LocalStack — which moved its core services behind a paid plan.

What's new in v1.1.0

Amazon Cognito — full emulation

This was the most requested feature since launch. v1.1.0 ships complete Cognito support across both planes:

User Pools (cognito-idp)

Full user lifecycle: SignUp, ConfirmSignUp, AdminCreateUser, AdminDeleteUser, AdminGetUser, ListUsers
Auth flows: USER_PASSWORD_AUTH, ADMIN_USER_PASSWORD_AUTH, REFRESH_TOKEN_AUTH, USER_SRP_AUTH (returns PASSWORD_VERIFIER challenge)
FORCE_CHANGE_PASSWORD challenge on first login
Self-service: ForgotPassword, ConfirmForgotPassword, ChangePassword, GetUser, DeleteUser
Groups, domains, MFA config, tags — all covered

Identity Pools (cognito-identity)

CreateIdentityPool, GetId, GetCredentialsForIdentity, GetOpenIdToken
SetIdentityPoolRoles, GetIdentityPoolRoles
Federated identity: MergeDeveloperIdentities, UnlinkIdentity

OAuth2

POST /oauth2/token — client_credentials flow, returns stub Bearer token

Stub JWTs are structurally valid base64url tokens — they pass format checks in most SDKs without needing real crypto.

import boto3

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

# Create a pool
pool = idp.create_user_pool(PoolName="my-app")
pool_id = pool["UserPool"]["Id"]

# Sign up a user
idp.sign_up(
    ClientId="local",
    Username="alice@example.com",
    Password="Password123!",
    UserAttributes=[{"Name": "email", "Value": "alice@example.com"}],
)

# Confirm and authenticate
idp.admin_confirm_sign_up(UserPoolId=pool_id, Username="alice@example.com")
resp = idp.initiate_auth(
    AuthFlow="USER_PASSWORD_AUTH",
    AuthParameters={"USERNAME": "alice@example.com", "PASSWORD": "Password123!"},
    ClientId="local",
)
print(resp["AuthenticationResult"]["AccessToken"])

644 tests — one file, all passing

We merged a separate QA test file into the main suite and fixed every test bug we found along the way:

test_s3_list_v1_marker_pagination — NextMarker only returned when Delimiter is set (AWS spec)
test_iam_inline_user_policy — boto3 deserialises PolicyDocument as a dict, not a string
test_kinesis_at_timestamp_iterator — boto3 already returns Data as bytes, no need to base64-decode
test_rds_snapshot_crud / test_rds_deletion_protection — added finally cleanup so containers are deleted after each test

644 tests across all 25 services. Single file. All passing.

Docker volume leak — fixed

This one was subtle. Every RDS (CreateDBInstance) and ElastiCache (CreateCacheCluster) call spins up a real Docker container. The postgres and mysql images declare VOLUME /var/lib/postgresql/data — so Docker was creating an anonymous volume for every container, even after the container was removed.

After 20 test runs: 30+ dangling volumes, 600MB+ of wasted space.

Two fixes:

tmpfs on containers.run() — postgres/mysql data lives in container RAM. No volume created.
container.remove(v=True) in reset() — volumes are removed with the container.

Before: 32 dangling volumes after 3 test runs
After:  2 volumes total (ministack + redis, always)

Clean up what you already have:

make purge

`make purge` — safe cleanup

purge: stop-compose
    docker rm -f $(docker ps -aq --filter "label=ministack") 2>/dev/null || true
    docker volume prune -f
    rm -rf ./data/s3/*

Every container MiniStack spins up is labelled ministack=true. The purge target uses that label — it won't touch your other Redis, Postgres, or MySQL containers.

Bug fixes

Lambda GetFunctionConcurrency — was returning 404 after DeleteFunctionConcurrency. Now returns {} matching AWS behaviour
ElastiCache ModifyCacheParameterGroup — parameter key format was wrong (member vs ParameterNameValue). Modified params were silently ignored
RDS ModifyDBInstance — DeletionProtection=False with ApplyImmediately=True now correctly applies immediately
Cognito GetCredentialsForIdentity — response field is SecretKey (correct boto3 wire name)
Port conflict on pip install — ministack now prints a clear error if port 4566 is already in use instead of a raw uvicorn traceback

AWS CLI docs fix

A user reported credentials failing. The README was showing aws configure --profile local but then omitting --profile local from the example commands. Fixed — two working options now documented:

Option A — environment variables

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

Option B — named profile

aws configure --profile local
# Access Key: test / Secret: test / Region: us-east-1

aws --profile local --endpoint-url=http://localhost:4566 s3 mb s3://my-bucket

Get it

# PyPI
pip install --upgrade ministack

# Docker
docker pull nahuelnucera/ministack:latest
docker compose up -d

GitHub: github.com/Nahuel990/ministack

25 AWS services. Free. MIT licensed. No account required.

What's next

SFN Activities (CreateActivity, GetActivityTask) — already requested
State persistence for Secrets Manager, SSM, DynamoDB — PERSIST_STATE=1 currently only covers API Gateway
ACM — last item on the original roadmap

Issues and PRs welcome.

LocalStack Is Dead. MiniStack Runs Real Databases for Free.

Nahuel Nucera — Sat, 28 Mar 2026 15:14:30 +0000

LocalStack archived its repo on March 23. Pipelines are breaking everywhere. Here's a drop-in replacement that actually spins up real Postgres, Redis, and Docker containers — no account, no API key, MIT licensed.

If you woke up this week to broken pipelines, you're not alone.

LocalStack archived its public GitHub repository and moved every image behind mandatory authentication. No warning in your docker-compose.yml. No deprecation period for CI. Just — gone.

The usual suspects have appeared: Moto, Floci, individual service emulators. But one project stands out for a reason nobody else is doing — it runs real infrastructure instead of faking it.

MiniStack: The One That Doesn't Fake It

docker run -p 4566:4566 nahuelnucera/ministack

No account. No API key. No telemetry. No BSL license. MIT, forever.

Existing --endpoint-url configs, boto3 clients, Terraform providers, and CDK stacks work without code changes.

aws --endpoint-url=http://localhost:4566 s3 mb s3://my-bucket
aws --endpoint-url=http://localhost:4566 sqs create-queue --queue-name my-queue
aws --endpoint-url=http://localhost:4566 dynamodb list-tables

The Killer Feature: Real Infrastructure

Most AWS emulators fake everything in memory. MiniStack doesn't — not where it matters.

RDS creates actual database containers:

import boto3
import 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
conn = psycopg2.connect(
    host=endpoint["Address"],
    port=endpoint["Port"],
    user="admin",
    password="password",
    dbname="appdb",
)

That conn is talking to a real Postgres process. Not a mock. Not an in-memory fake. A real database you can inspect with psql.

Same story for:

ElastiCache → spins up a real Redis container
ECS → runs real Docker containers
Athena → executes real SQL via DuckDB
Lambda → real Python execution with warm starts between invocations

Why This Matters

If a test says "insert a row into RDS and read it back," the question is: is it testing application code or testing someone's mock of Postgres?

Moto is excellent for unit tests. But when integration confidence is what matters — when SQL migrations need to actually run, connection pooling needs to actually work, Redis TTLs need to actually expire — real infrastructure beats mocks. Locally.

That's the gap MiniStack fills.

23 Services, One Port

Service	Real Infra?	Notes
S3	In-memory + persistence	Full API including presigned URLs
SQS	In-memory	FIFO, dead-letter, visibility timeout
SNS	In-memory	Subscriptions, filtering
DynamoDB	In-memory	Streams, GSI, LSI
Lambda	✅ Real Python execution	Warm starts between invocations
RDS	✅ Real Postgres/MySQL	Actual Docker containers
ElastiCache	✅ Real Redis	With IAM auth support
ECS	✅ Real Docker	Actual container execution
Athena	✅ Real SQL (DuckDB)	Optional
IAM / STS	In-memory	Policies, roles, assume-role
Secrets Manager	In-memory	Full CRUD + rotation
SSM Parameter Store	In-memory	String, SecureString, StringList
EventBridge	In-memory	Rules, targets, patterns
Kinesis	In-memory	Shards, iterators
CloudWatch Logs	In-memory	Log groups, streams, events
CloudWatch Metrics	In-memory	Put/Get metric data
SES	In-memory	Send email (logged, not delivered)
Step Functions	In-memory	State machine execution
Glue	In-memory	Catalog, crawlers

How It Compares

	MiniStack	Floci	Moto	LocalStack (was)
License	MIT	MIT	Apache 2.0	BSL (was Apache)
Account required	No	No	No	Yes (now)
Real databases	✅	❌	❌	Pro only
Real containers (ECS)	✅	❌	❌	Pro only
Image size	~150 MB	~90 MB	N/A (library)	~1 GB
RAM at idle	~30 MB	~13 MB	N/A	~500 MB
Approach	Docker service	Docker service	In-process mock	Docker service
Best for	Integration tests, real infra	Quick emulation, CI	Python unit tests	—

5-Minute Migration from LocalStack

Step 1: Swap the image

# docker-compose.yml
services:
  # OLD
  # localstack:
  #   image: localstack/localstack

  # NEW
  ministack:
    image: nahuelnucera/ministack
    ports:
      - "4566:4566"
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
    environment:
      - REDIS_HOST=redis

  redis:
    image: redis:7-alpine
    ports:
      - "6379:6379"

Step 2: There is no step 2.

Same port. Same endpoint format. Same AWS API. boto3 clients, Terraform configs, and CDK stacks don't change.

GitHub Actions

- name: Start MiniStack
  run: |
    docker run -d -p 4566:4566 nahuelnucera/ministack
    sleep 2
    curl http://localhost:4566/_localstack/health

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

The Footprint Difference

LocalStack's image was over 1 GB and consumed ~500 MB at idle. That's a real cost in CI — especially on GitHub Actions free tier or when running parallel jobs.

MiniStack is ~150 MB and idles at ~30 MB. CI spins up faster, laptop fans stay quiet, and there's headroom for actual test workloads.

FAQ

Is this production-ready?
It's a local dev and CI tool. Don't expose it to the internet — it has no authentication by design. That's the whole point.

What about Moto?
Moto is the right choice for Python unit tests where in-process speed matters and Docker isn't wanted. MiniStack is the right choice when real infrastructure is needed — actual database connections, real Redis commands, real container execution.

What about Floci?
Floci is a solid project with faster startup and smaller footprint. MiniStack's differentiator is real infrastructure — actual Postgres/Redis containers out of the box, not in-memory fakes.

Will this stay free?
MIT is MIT. Fork it, embed it, sell it. No "community vs pro" split. No feature gates. No bait-and-switch.

Ministack, a free LocalStack alternative. v1.0.7 released

Nahuel Nucera — Fri, 27 Mar 2026 21:07:42 +0000

MiniStack is a free, MIT-licensed local AWS emulator — a drop-in replacement for LocalStack that runs 23 services on a single port with no account required. Today we're shipping v1.0.7.

What's new

Amazon Data Firehose

MiniStack now emulates Amazon Data Firehose (all 12 API operations):

import boto3, base64, json

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

# Create a delivery stream with S3 destination
fh.create_delivery_stream(
    DeliveryStreamName="my-stream",
    DeliveryStreamType="DirectPut",
    ExtendedS3DestinationConfiguration={
        "BucketARN": "arn:aws:s3:::my-bucket",
        "RoleARN":   "arn:aws:iam::000000000000:role/firehose-role",
        "BufferingHints": {"SizeInMBs": 1, "IntervalInSeconds": 60},
        "Prefix": "events/",
    },
)

# Put records — S3 destination writes synchronously to the local S3 emulator
fh.put_record(
    DeliveryStreamName="my-stream",
    Record={"Data": base64.b64encode(json.dumps({"event": "click"}).encode())},
)

# Batch ingestion
records = [{"Data": base64.b64encode(f"record-{i}".encode())} for i in range(100)]
resp = fh.put_record_batch(DeliveryStreamName="my-stream", Records=records)
assert resp["FailedPutCount"] == 0

Full operation coverage:

CreateDeliveryStream / DeleteDeliveryStream / DescribeDeliveryStream / ListDeliveryStreams
PutRecord / PutRecordBatch
UpdateDestination — concurrency-safe via CurrentDeliveryStreamVersionId
TagDeliveryStream / UntagDeliveryStream / ListTagsForDeliveryStream
StartDeliveryStreamEncryption / StopDeliveryStreamEncryption

Destination types accepted: ExtendedS3, S3 (deprecated), HttpEndpoint, Redshift, OpenSearch, Splunk, Snowflake, Iceberg. S3 destinations write records to the local S3 emulator synchronously. All other destination types buffer records in-memory (great for testing your producer code without a real backend).

MiniStack's Firehose actually fixes 4 known LocalStack Community bugs:

ExtendedS3DestinationConfiguration + PutRecord crashes in LocalStack (issue #5936) — works fine here
KinesisStreamAsSource stream creation sometimes fails in LocalStack (issue #1758) — never fails here
DescribeDeliveryStream doesn't return HttpEndpointDestinationDescription in LocalStack (issue #3384) — returned correctly here
Elasticsearch KeyError: 'IndexName' in LocalStack (issue #5047) — no crash here

Virtual-hosted style S3

AWS SDKs can address S3 buckets via the host header (bucket.s3.amazonaws.com). MiniStack now supports the local equivalent:

s3 = boto3.client(
    "s3",
    endpoint_url="http://localhost:4566",
    config=Config(s3={"addressing_style": "virtual"}),
    ...
)
# Requests sent as: http://my-bucket.localhost:4566/key
# MiniStack rewrites to path-style internally — transparent to your code

DynamoDB `OR`/`AND` expression fix

A subtle parser bug caused ConditionExpression and FilterExpression to crash with Invalid expression: Expected RPAREN, got NAME_REF when using numeric ExpressionAttributeNames keys (#0, #1) — which PynamoDB generates automatically on composite key tables.

# This now works correctly
dynamodb.put_item(
    TableName="my-table",
    Item={"pk": {"S": "row#1"}, "sk": {"S": "row#1"}, "updated_at": {"S": "2026-01-01T00:00:00Z"}},
    ConditionExpression="(attribute_not_exists (#0) OR #1 <= :0)",
    ExpressionAttributeNames={"#0": "pk", "#1": "updated_at"},
    ExpressionAttributeValues={":0": {"S": "2026-01-01T00:00:00Z"}},
)

Root cause: The recursive-descent expression evaluator used Python's or/and operators directly (left = left or self._and_expr()). When left was truthy, Python short-circuited and never consumed the right-hand tokens from the stream. The outer expect('RPAREN') then found the wrong token. Fixed by always eagerly evaluating both sides before applying the logical operator.

By the numbers

23 AWS services on a single port
450 integration tests, all passing against the Docker image
~150 MB Docker image, ~30 MB memory at idle, ~2s startup

Get it

# Docker
docker run -p 4566:4566 nahuelnucera/ministack:v1.0.7

# Or docker-compose
curl -O https://raw.githubusercontent.com/Nahuel990/ministack/main/docker-compose.yml
docker compose up

Then point any AWS SDK at http://localhost:4566:

aws --endpoint-url http://localhost:4566 firehose list-delivery-streams

Docker Hub: hub.docker.com/r/nahuelnucera/ministack

Full changelog and source: github.com/Nahuel990/ministack

MiniStack v1.0.4: API Gateway v2, Lambda Warm Workers, SNS SQS Fanout, State Persistence

Nahuel Nucera — Thu, 26 Mar 2026 09:00:13 +0000

MiniStack is a free, open-source, MIT-licensed drop-in replacement for LocalStack — 21 AWS services on a single port, no account, no license key, no telemetry.

v1.0.4 is out today. This post covers everything that landed across the v1.0.2–v1.0.4 wave: the big features, the architectural decisions behind them, and the fixes that got us to a clean 379-test run.

docker run -p 4566:4566 nahuelnucera/ministack

Why this exists

LocalStack moved its core services behind a paid plan. If you were using LocalStack Community for local dev and CI/CD, you now hit a paywall for S3, SQS, Lambda, and most things that matter.

MiniStack covers the same surface — and goes further in a few areas — at $0, MIT licensed, forever. The full comparison is on ministack.org, but the short version: same developer experience, 150 MB image vs ~1 GB, ~30 MB RAM at idle vs ~500 MB, ~2 s startup vs 15–30 s.

What shipped in v1.0.2–v1.0.4

API Gateway HTTP API v2 — full control plane + data plane

This was the biggest missing piece. v1.0.2 delivered the complete API Gateway v2 implementation.

Control plane covers the full resource tree:

APIs: CreateApi, GetApi, GetApis, UpdateApi, DeleteApi
Routes: full CRUD, including {param} path parameter placeholders and {proxy+} greedy matching
Integrations: AWS_PROXY (Lambda) and HTTP_PROXY (arbitrary HTTP backends)
Stages, Deployments, Authorizers (JWT + Lambda), Tags

Data plane is the part most emulators skip. In MiniStack, execute-api requests are dispatched by host header — {apiId}.execute-api.localhost — before normal service routing. That means your actual API calls hit the right Lambda function with a proper payload format 2.0 envelope:

import boto3

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

api = apigw.create_api(Name="my-api", ProtocolType="HTTP")
api_id = api["ApiId"]

apigw.create_route(ApiId=api_id, RouteKey="GET /hello")
apigw.create_integration(
    ApiId=api_id,
    IntegrationType="AWS_PROXY",
    IntegrationUri=f"arn:aws:lambda:us-east-1:000000000000:function:my-func",
    PayloadFormatVersion="2.0",
)

import requests
resp = requests.get(f"http://{api_id}.execute-api.localhost:4566/hello")
print(resp.json())

Route matching supports path parameters and {proxy+} greedy segments. There was a subtle bug in the initial implementation: re.escape was applied before {param} substitution, which meant every parameterised route silently fell through to a 404. Fixed in v1.0.2.

Authorizers ship with full CRUD — JWT and Lambda authorizer types, with identitySource stored and returned as an array of strings matching the AWS spec (was incorrectly a single string in the initial cut).

Lambda warm/cold start worker pool

Prior to v1.0.2, every Lambda invocation spawned a fresh subprocess. That's fine for correctness but misses a whole class of bugs that only appear when your handler module is imported once and invoked repeatedly.

core/lambda_runtime.py now maintains a persistent Python subprocess per function. The handler module is imported on first invocation (cold start), and subsequent calls reuse the warm worker without re-importing. Workers respawn automatically on crash.

This matters for three reasons:

Correctness — module-level state (caches, connection pools, counters) behaves the same as in real Lambda
Speed — warm invocations are significantly faster in CI
Bug surface — you'll catch issues with global state that a fresh-subprocess model would mask

import boto3

_client = None

def handler(event, context):
    global _client
    if _client is None:
        _client = boto3.client("s3", endpoint_url="http://localhost:4566",
                               aws_access_key_id="test", aws_secret_access_key="test",
                               region_name="us-east-1")
    return {"buckets": [b["Name"] for b in _client.list_buckets()["Buckets"]]}

In MiniStack, that _client initialization happens exactly once per function, just like AWS.

SNS → SQS fanout and SNS → Lambda dispatch

sqs protocol subscriptions now deliver messages directly to SQS queues with the standard SNS JSON notification envelope. lambda protocol subscriptions invoke the Lambda function via _execute_function() with a Records[].Sns event structure. Both were stubs in v1.0.1 — SNS→SQS was wired in v1.0.2, SNS→Lambda was a no-op that got fixed in the same release.

sns = client("sns")
sqs = client("sqs")

topic = sns.create_topic(Name="events")["TopicArn"]
queue = sqs.create_queue(QueueName="consumer")
queue_url = queue["QueueUrl"]
queue_arn = sqs.get_queue_attributes(
    QueueUrl=queue_url, AttributeNames=["QueueArn"]
)["Attributes"]["QueueArn"]

sns.subscribe(TopicArn=topic, Protocol="sqs", Endpoint=queue_arn)
sns.publish(TopicArn=topic, Message="hello fanout")

msgs = sqs.receive_message(QueueUrl=queue_url)
body = json.loads(msgs["Messages"][0]["Body"])
print(body["Message"])  # hello fanout

Fanout is synchronous within the same process — consistent with how LocalStack handles it and good enough for unit/integration testing.

SQS → Lambda event source mapping

Full ESM lifecycle: CreateEventSourceMapping, DeleteEventSourceMapping, GetEventSourceMapping, ListEventSourceMappings, UpdateEventSourceMapping.

A background poller picks up messages from the configured SQS queue and delivers them to the target Lambda as batched events. Batch size and enabled state are configurable.

lam = client("lambda")
sqs = client("sqs")

queue_url = sqs.create_queue(QueueName="trigger-queue")["QueueUrl"]
queue_arn = sqs.get_queue_attributes(
    QueueUrl=queue_url, AttributeNames=["QueueArn"]
)["Attributes"]["QueueArn"]

lam.create_event_source_mapping(
    EventSourceArn=queue_arn,
    FunctionName="my-processor",
    BatchSize=10,
    Enabled=True,
)

sqs.send_message(QueueUrl=queue_url, MessageBody=json.dumps({"event": "order_placed"}))

State persistence

PERSIST_STATE=1 enables atomic state snapshots to disk. Writes go to a temp file first, then rename — so a crash mid-write doesn't corrupt the saved state. STATE_DIR controls where (default /tmp/ministack-state).

API Gateway state is fully persisted across container restarts. The persistence framework is designed so other services can adopt the same get_state() / load_persisted_state() pattern incrementally.

The reset endpoint (POST /_ministack/reset) clears in-memory state and, when PERSIST_STATE=1, also deletes STATE_DIR/*.json and S3_DATA_DIR contents — so a restart doesn't reload stale state. Also used in the test suite as a session-scoped autouse fixture to keep tests idempotent across repeated runs.

DynamoDB TTL enforcement

TTL was previously stored — TimeToLiveSpecification accepted and returned without error — but never acted on. Items just sat there forever. A background daemon thread (dynamodb-ttl-reaper) now scans all tables every 60 seconds and deletes items whose TTL attribute value is ≤ current epoch time.

Lambda Function URLs

Full CRUD: CreateFunctionUrlConfig, GetFunctionUrlConfig, UpdateFunctionUrlConfig, DeleteFunctionUrlConfig, ListFunctionUrlConfigs. State persisted in _function_urls. Was a 404 stub before.

SQS queue URL portability (v1.0.4)

QueueUrl values now read MINISTACK_HOST and GATEWAY_PORT env vars instead of hardcoding localhost:4566. This was causing silent failures in CI environments where MiniStack runs as a service container with a network alias.

services:
  ministack:
    image: nahuelnucera/ministack
    environment:
      MINISTACK_HOST: ministack
      GATEWAY_PORT: 4566
  app:
    environment:
      AWS_ENDPOINT_URL: http://ministack:4566

Before this fix, queue URLs returned http://localhost:4566/... regardless of configuration, and any SQS operation using that URL from another container would fail.

Bug fixes worth calling out

Several of these look fine in smoke tests but break real workloads.

execute-api credential scope misrouted to lambda — In core/router.py, the credential scope for execute-api requests was mapped to lambda instead of apigateway. Any data plane request was dispatched to the Lambda handler instead of the API Gateway data plane. Fixed in v1.0.2.

routeKey always "$default" in Lambda proxy events — The routeKey field was hardcoded to "$default" regardless of which route was matched. If your handler branched on event["routeKey"] — common in single-function routers — every request hit the default branch. Fixed to reflect the actual matched route key (e.g. "GET /users/{id}").

identitySource wrong type on Authorizers — Stored and returned as a plain string instead of an array of strings. boto3 raised a shape validation error on the response. Now returns ["$request.header.Authorization"] as the AWS spec requires.

DeleteFunctionUrlConfig returning {} body on 204 — boto3 expects an empty body on 204. The non-empty body caused a RemoteDisconnected exception. Fixed to return a true empty 204.

/_ministack/reset not cleaning disk — When PERSIST_STATE=1, reset cleared in-memory state but left STATE_DIR/*.json and S3_DATA_DIR intact. On the next restart, old state was reloaded. Fixed to delete persisted files as well.

Test idempotency — Tests with hardcoded resource names failed on a second run because the resources already existed. Fixed by wiring POST /_ministack/reset into a session-scoped autouse fixture in conftest.py.

Test suite: 54 → 379

v1.0.1 shipped with 54 integration tests. v1.0.4 has 379, all passing against both the in-process server and the Docker image.

The growth came from:

10 new tests covering previously untested paths: health endpoint, STS GetSessionToken, DynamoDB TTL, Lambda warm start, API Gateway execute-api Lambda proxy, $default catch-all, path parameter matching, 404 on missing route, EventBridge → Lambda dispatch
25 new tests for operations added post-v1.0.1: Kinesis shard split/merge, SSM label/tag operations, CloudWatch Logs retention/subscription/metric filters/Insights, CloudWatch composite alarms, EventBridge archives/permissions, DynamoDB UpdateTable, S3 versioning/encryption/lifecycle/CORS/ACL, Athena workgroup and batch operations
Full coverage of all v1.0.2 features: API Gateway control + data plane, SNS→SQS fanout, SQS→Lambda ESM, Lambda warm start, persistence, reset

Tests run against the Docker image — no mocking, no monkeypatching, real boto3 calls over the wire.

What's still on the roadmap

API Gateway REST API (v1)
Cognito — user pools, sign-up/sign-in
Route53 — hosted zones, record sets
ACM — certificate management
Firehose
Virtual-hosted style S3 (bucket.localhost:4566 routing)

Getting started

docker run -p 4566:4566 nahuelnucera/ministack

# With persistence and Redis sidecar
git clone https://github.com/Nahuel990/ministack
cd ministack
docker compose up -d

curl http://localhost:4566/_localstack/health

Works with boto3, AWS CLI, Terraform, CDK, Pulumi. Point endpoint_url at http://localhost:4566, credentials test/test, and you're done.

GitHub: github.com/Nahuel990/ministack
Docker Hub: hub.docker.com/r/nahuelnucera/ministack
Site: ministack.org

Stars, issues, and PRs welcome. Each service is a single self-contained Python file — adding a new one is straightforward.

Forem: Nahuel Nucera

What landed in MiniStack between 1.2.0 and 1.3.30

MiniStack 1.3.30 is out — here's what shipped recently

Highlights since 1.3.20

Wire-format parity (what makes the project worth using)

Try it

What landed in MiniStack between 1.2.0 and 1.3.30

New services

Lambda

Step Functions aws-sdk:* integrations

CloudFormation

Infrastructure

Multi-tenancy correctness

Wire-format fixes worth knowing

Get it

MiniStack Now Emulates Amazon EKS — Free, Open-Source AWS Emulator v1.2.20

EKS Joins the Free AWS Emulator

EKS Emulation in Action

Why This Matters

What MiniStack Emulates (40+ Services)

How It Compares

Try It

MiniStack: Free Local AWS Emulator + Testcontainers Module + AWS CLI Built In

TL;DR

What is MiniStack?

Testcontainers Module

AWS CLI Bundled (v1.2.9)

The Flea Hunt: 62 Bugs Found and Fixed

Quick Start

Links

How we made Step Functions call any AWS service locally

The generic dispatcher

How it works

What else ships with MiniStack

Try it

Getting started testing AWS with MiniStack in under 10 minutes

The problem

The setup

What the guide covers

1. S3 — Create buckets and upload files

2. DynamoDB — Create tables and query data

3. SQS — Send and receive messages

4. Lambda — Deploy and invoke functions

Why this matters

The full guide

MiniStack vs Floci vs LocalStack: Honest Performance Benchmark (April 3rd 2026)

TL;DR

Methodology

Image Size

Startup Time

API Latency (median of 5 runs, single operation)

S3

SQS

DynamoDB

Other Services

Throughput

Memory Usage

Service Coverage

Feature Comparison

What Floci Does Better

What MiniStack Does Better

When to Use What

Benchmark Reproducibility

Versions Tested

Ministack, the best alternative to Localstack

We built a free LocalStack alternative — after last week’s changes

Introducing MiniStack

What started small grew fast

The key difference: real infrastructure

Services that are now paid elsewhere — free here

Same developer experience

Why we built this

Try it

MiniStack v1.1.2 — Cognito, EC2, EMR, 656 Tests, and Zero Docker Leaks

What's new in v1.1.0

Amazon Cognito — full emulation

644 tests — one file, all passing

Docker volume leak — fixed

make purge — safe cleanup

Bug fixes

`make purge` — safe cleanup

DynamoDB `OR`/`AND` expression fix