DEV Community: Nahuel Nucera

Limp Mode: building a car mechanic that runs offline on a 4B model

Nahuel Nucera — Sun, 14 Jun 2026 10:50:00 +0000

Built for the Build Small Hackathon (Hugging Face and Gradio), Backyard AI track. A
fine-tuned 4B model, a 1.3B vision model, a deterministic safety layer, and a 202-case
benchmark with one number that has to stay at zero.

Seven years ago I hit a bump in a Fiat and the engine died. No damage, no warning light,
just dead, on a road with no signal. The cause turned out to be a crash safety switch
that cuts the engine after an impact. The reset was a hidden button near my knee,
documented on a page of a manual that was not in the car. A tow truck and a mechanic
later, I had the lesson this project is built on: the moment you most need information
about your car is exactly the moment you have no internet.

Limp Mode is an offline roadside copilot. You photograph the dashboard light, pick it
from a wall of warning lights drawn the way they look on a real dash, describe the noise
in English or Spanish, or enter an OBD code. It answers with a STOP, CAUTION, or DRIVE
verdict, the hidden cause when there is one, and step by step self rescue, because "drive
carefully to a garage" is useless in a dead zone.

Deterministic skeleton, small-model flesh

The design rule: anything that has to be right is not generated.

layer	mechanism
OBD code to meaning	3,369-code database (SAE J2012)
dashboard symbol to meaning	closed world of 64 telltales; vision proposes, the driver confirms by tapping the glyph
severity floor	hard rules: brakes, oil pressure, overheating, fuel smell, flashing CEL, and flooding can never be downgraded by the model
hidden causes	38 verified entries (inertia switches, EV 12V bricks, shift-lock overrides), retrieved and rendered verbatim
roadside procedures	15 step by step guides, rendered verbatim, never paraphrased
free-form triage	Qwen3.5-4B, fine-tuned, strict JSON contract

The model only does what only a model can do: read a messy human description of a noise
and reason about it. Everything else is data.

A benchmark with a zero in it

Before training anything, we built a 202-case suite (52 stop, 96 caution, 54 drive)
across seven categories. Two headline metrics: verdict accuracy, and dangerous-as-safe
(expected STOP, answered DRIVE), which must be exactly zero. Overcaution is also a
failure, so a quarter of the suite is benign cases designed to punish panic.

What the measurements caught

Naive RAG made the model worse. Zero-shot, the model alone scored 88.1% accuracy but
surfaced the hidden-cause knowledge only 74% of the time. The first retrieval attempt
pushed knowledge to 100% and crashed accuracy to 59.5%: irrelevant but lexically similar
knowledge-base entries scared the model into overcaution on ordinary cases. The fix was
IDF-weighted retrieval, a prompt contract that treats hits as candidates to ignore unless
they clearly match, and training data that includes noisy retrievals whose correct answer
is to ignore the context.

Our own safety floor was the second biggest error source. The model is told to
over-flag plausible hazards because the flags feed the floor. The floor treated any flag
as a hard trigger, so "slight pull when braking" got honestly flagged for brakes and
slammed from the correct CAUTION up to STOP. Fourteen of seventeen failures in one run
were the floor, not the model. The fix: hard evidence (text keywords, confirmed symbols,
OBD codes) gets the full floor, while a bare model flag can raise at most to CAUTION. The
full pipeline then reached 90.5% on the seed suite, above the bare model, with knowledge
at 100% and dangerous-as-safe still zero.

The training-data gate found a bug in the safety system. Every training example passes
deterministic gates plus decontamination against the eval suite. The floor-consistency
gate started rejecting perfectly good inertia-switch examples, because the floor keyword
list included the bare word "fire", which matches "the engine will not fire". That bug
would have hit real users. A verifier built to check the data ended up debugging the
product.

We red-teamed the human-written layer too. The 15 roadside procedures were checked
line by line against AA, RAC, NHTSA, CDC, and manufacturer guidance. Thirteen stood, two
had real problems. Our "drive in a truck's spray shadow" tip for dead wipers was the
opposite of the correct advice (truck spray blinds you, stay back), and our warning
triangle distances matched no actual jurisdiction while several countries now prohibit
placing triangles on motorways at all. Both fixed.

Training: Modal, and a week of dependency archaeology

The triage model is a LoRA fine-tune of Qwen3.5-4B (rank 32, completion-only loss, 3
epochs) trained on Modal over 760 quality-gated examples. The honest part of the story is
that the training code worked on the first try and the environment did not, eleven times.
The chain: one trainer library pinned an older version of transformers that did not know
Qwen3.5, so we dropped it; the next library did the same, so we dropped that too; and the
GGUF converter's own requirements file silently downgraded both PyTorch (to a CPU build)
and transformers on every rebuild. The fix was to make the CUDA PyTorch and the correct
transformers the final image layers, with a build-time assertion that fails the build if
either was clobbered.

One more small-model trap worth writing down: the converter declared a multi-token
prediction head in the GGUF metadata but wrote none of its tensors, so the file would not
load until that metadata was set back to zero.

Results

Both rows run through the identical pipeline, so the difference is the fine-tune alone.

stage	accuracy	dangerous-as-safe	schema valid	knowledge
base Qwen3.5-4B	83.2%	0	99.5%	98.9%
fine-tuned	92.6%	0	100%	97.9%

A 9.4 point gain in verdict accuracy, with the dangerous-as-safe count held at zero and
schema validity at 100%. The fine-tune scores 100% on OBD-code and dashboard-symbol cases
and 94.6% on hidden-cause cases; the soft spots it leaves are benign cases (81%, a little
residual overcaution) and Spanish (84%).

What it costs

The whole stack, both models quantized, all the knowledge bases, and the front end, runs
on a laptop with the network off, answering in roughly 15 to 20 seconds. The deployed
Space runs the same pipeline on free ZeroGPU hardware.

Honest limitations

The hidden-cause knowledge base covers 38 entries; coverage is the ceiling, and a miss
means the model reasons unaided. Vision recall on a full dashboard is partial at 1.3B,
which is exactly why the product never trusts it: every detected light is confirmed by the
driver's tap before it feeds the deterministic layer. The procedures are general; a
procedures database for your specific car would be better. That is the roadmap: the
owner's manual, finally useful, finally offline.

Try it: https://huggingface.co/spaces/build-small-hackathon/limp-mode

We gave Kiro a brain for AWS, locally, for free

Nahuel Nucera — Thu, 28 May 2026 08:21:03 +0000

We built MiniStack (a local AWS emulator) when LocalStack moved its core services behind a paywall. It runs on a single port at http://localhost:4566, emulates around 60 AWS services, and costs nothing. Day to day, we use it for testing AWS code and for prototyping new services without spending a cent on a real account.

The piece that was missing was the editor side of the loop. We work in Kiro. Kiro is a strong agentic IDE. But every new AWS workflow inside the editor started with the same overhead: telling Kiro where to point the SDK clients, reminding it of the testing patterns we use, walking it through which service does what for the case at hand. Repetitive context we'd already written down somewhere else.

So we pulled all of it into a Kiro Power. The Power ships steering files for the services we use most, a testing workflow file, and a manifest that activates the moment you mention MiniStack or AWS in chat. Kiro picks it up automatically, no manual prompting.

That's what this post is about. It's called MiniStack × Kiro, it's open source, and it's about removing the repetitive context-loading step from every AWS session.

What changes once you install it

Kiro picks up specific behaviors the moment you mention AWS or MiniStack in chat:

It configures your boto3, AWS CLI, Terraform, and CDK setups against localhost:4566 with the right test credentials, without asking you for them.
It writes service-specific code that actually runs against MiniStack. Not pseudocode. Real S3 calls. Real DynamoDB conditional updates. Real Step Functions ASL.
It walks you through services you don't know yet. There are steering files for S3, SQS, SNS, DynamoDB, Lambda, IAM, Step Functions, EventBridge, API Gateway, Cognito, and CloudWatch. Each one is a hands-on guide written for the local-first workflow.
It knows the reset endpoint, so when you ask it to run a test scenario from scratch, it resets the right state instead of polluting it.
It handles multi-tenancy properly. MiniStack scopes resources by your access-key-as-account-ID. The Power knows this and reuses it when you want isolated environments per developer or per CI lane.

The steering files were extracted from real workflows we run every week, not synthesised.

Installing it

Two paths, both take under a minute.

From the GitHub repo:

Open Kiro, click the Powers icon in the sidebar.
Add Custom Power, then GitHub Repository.
Paste https://github.com/ministackorg/ministack-power.
Click Add.

From a local folder, if you cloned it:

Open Kiro, click the Powers icon.
Add Custom Power, then Local Directory.
Paste the absolute path to the folder you cloned.
Click Add.

That's it. The Power activates automatically when you talk to Kiro about AWS or MiniStack.

You'll also want MiniStack itself running. One line:

pip install ministack && ministack

It boots in around two seconds and uses around 30 MB of RAM at idle. Health check:

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

What it looks like in practice

A few examples from real sessions, since "Kiro plus a Power" sounds abstract until you see it doing work.

S3 presigned URLs.
A Python script that uploads a file via presigned PUT, downloads it via presigned GET, then verifies the round-trip. The Power pulls in the S3 steering file, the script gets generated pointed at localhost:4566 with the right SigV4 settings, runs, and you see the output. No clarifying questions about endpoint configuration. No "let me check the AWS docs first."

DynamoDB conditional writes.
Three test cases against the local DynamoDB exercising ConditionExpression plus ReturnValuesOnConditionCheckFailure=ALL_OLD. The case where the condition fails and the API returns the existing item in the error body is the one most emulators get wrong; MiniStack handles it correctly, and the Power knows to test for it.

Step Functions ASL.
A state machine with a Map iterator over 100 items, executed locally, with the per-iteration results inspected via GetExecutionHistory. The whole loop happens on the laptop. No AWS bill. No clean-up.

Serverless REST API.
API Gateway plus Lambda plus DynamoDB, CRUD endpoints, end-to-end. The Power has a dedicated steering file for this pattern. Kiro scaffolds the project, writes the Lambda handlers, wires the API Gateway integrations, creates the DynamoDB table, and runs the end-to-end test against MiniStack. The whole thing takes minutes instead of the hour you'd burn on real AWS worrying about IAM roles and accidentally provisioning something you forgot to tear down.

Why this matters more than "Kiro got smarter"

What this combination removes from the loop is the interesting part.

When you're learning AWS, the cost of an experiment is friction. Spinning up a real account, creating a sandbox, watching for forgotten resources, dealing with permissions. Even if the dollar amount is small, the cognitive load isn't. A lot of people give up on learning new AWS services not because the services are hard, but because the friction of trying things is high.

When you're testing existing AWS code, the cost is reliability. If your CI pipeline depends on LocalStack's free tier (no longer free) or on shared sandbox accounts, you're at the mercy of something outside your control. MiniStack runs on the laptop. The Power makes it talk fluently with Kiro. The whole loop becomes a closed system you own.

That's the value. It's not "AI plus AWS." It's the removal of friction from both sides.

Some things to know

MiniStack is MIT licensed. The Power is MIT licensed. There's no upsell, no paid tier, no telemetry. It runs entirely on your machine.

You can use the Power without MiniStack. Kiro will still pick up the steering content and apply it. But the loop only closes when both are running.

The Power doesn't ship steering for every AWS service yet. It covers the 10 services we use daily plus the serverless-REST-API pattern. Pull requests welcome at github.com/ministackorg/ministack-power. If you want a service added, opening an issue is enough.

State persistence is opt-in. Set PERSIST_STATE=1 when you start MiniStack and it survives restarts. The Power knows about this and will mention it when you're building anything that needs durability across runs.

What's next

Two Power variants on the backlog:

A Terraform-first variant. Same steering, but every example is terraform apply against the local endpoint instead of boto3 or CLI. Useful for infra teams who think in HCL.
A CDK-first variant. Same idea, but using cdk synth and cdk deploy --endpoint-url. Useful for application teams who already use CDK.

If either sounds useful, open an issue on the repo so we know to prioritise it.

Try it

pip install ministack && ministack

Then install the Power in Kiro using https://github.com/ministackorg/ministack-power. Talk to Kiro about anything AWS. You'll feel the difference within a few prompts.

If something breaks, file an issue at github.com/ministackorg/ministack-power/issues. If something works well, tell people. That's how this stuff spreads.

Links:

MiniStack: github.com/ministackorg/ministack
The Power: github.com/ministackorg/ministack-power
PyPI: pypi.org/project/ministack/
Docker Hub: hub.docker.com/r/ministackorg/ministack

MiniStack now emulates MWAA. Develop and test Airflow DAGs locally, skip the $353/month

Nahuel Nucera — Sun, 17 May 2026 10:57:31 +0000

MWAA costs $353/month. That's $0.49/hour, 24/7, just for the environment to exist. Whether you're actively developing DAGs, running tests in CI, or doing nothing at all; you pay.

MiniStack now emulates MWAA. You can develop and validate Airflow DAGs locally. DAG structure, task routing, API calls on a single Docker container. No AWS environment needed until you deploy to production.

If you had a dedicated MWAA environment for development and testing, that's $353/month you no longer need.

And MWAA is just one piece. Here's what a full integration test suite actually costs on AWS.

The scenario

A typical integration test suite that validates cloud infrastructure:

Test Type	What It Validates	AWS Services Used
Table schema checks	Partition keys, GSIs, TTL, billing, PITR	DynamoDB
Parameter verification	Config values, paths, naming	SSM Parameter Store
Object storage ops	Upload, list, download, cleanup	S3
ETL job execution	Data transformation pipeline	Glue
Query validation	Output correctness	Athena
Workflow orchestration	DAG structure, task routing	MWAA (Airflow)
Serverless functions	Event processing, API handlers	Lambda
Message queues	Pub/sub, FIFO ordering	SQS

Per test run: ~50 DynamoDB operations, ~10 S3 operations, 9 Glue jobs (10 workers, ~4 min each), 20 Athena queries, 4 MWAA API calls.

Cost per test run by region

Component	Cost	Dominance
Glue (9 jobs x 10 workers x 4 min)	$2.64	99.9%
DynamoDB (50 reads + 25 writes)	$0.0001	~0%
S3 (~25 requests, 1MB data)	$0.0001	~0%
Athena (20 queries x 10MB min)	$0.001	~0%
SSM (3 GetParameter calls)	Free	0%
MWAA (API calls only, env already running)	$0.00	0%

Per-run cost is identical across all regions: ~$2.64 (Glue pricing is uniform)

The only regional variation is in DynamoDB and S3, which together account for less than $0.001 per run — negligible.

AWS pricing by region

Services with uniform global pricing

Service	Unit	Price
Glue ETL	DPU-hour (G.1X)	$0.44
Athena	Per TB scanned (10MB min)	$5.00
MWAA mw1.small	Per hour	$0.49
MWAA mw1.medium	Per hour	$0.74
Lambda	Per 1M requests	$0.20
Lambda	Per GB-second	$0.0000166667
SQS Standard	Per 1M requests	$0.40
SSM Standard	API calls + storage	Free

DynamoDB on-demand (per 1M request units)

Region	Writes (WRU)	Reads (RRU)	vs US baseline
us-east-1 (N. Virginia)	$0.625	$0.125	baseline
us-west-2 (Oregon)	$0.625	$0.125	same
eu-west-1 (Ireland)	$0.705	$0.142	+13%
eu-central-1 (Frankfurt)	$0.763	$0.153	+22%
ap-southeast-1 (Singapore)	$0.710	$0.143	+14%
ap-northeast-1 (Tokyo)	$0.715	$0.143	+14%

S3 Standard

Region	Storage $/GB/mo	PUT per 1K	GET per 1K
us-east-1	$0.023	$0.005	$0.0004
us-west-2	$0.023	$0.005	$0.0004
eu-west-1	$0.023	$0.005	$0.0004
eu-central-1	$0.0245	$0.0054	$0.00043
ap-southeast-1	$0.025	$0.005	$0.0004
ap-northeast-1	$0.025	$0.0047	$0.00037

Monthly cost: AWS vs MiniStack

AWS monthly cost by test frequency

Frequency	Runs/month	Test Cost	MWAA env (24/7)	Total
2x/week	9	$24	$353	$377
1x/day	30	$79	$353	$432
3x/day	90	$238	$353	$591
5x/day	150	$396	$353	$749
10x/day	300	$792	$353	$1,145

Note: MWAA is typically shared infrastructure (dev + test + orchestration), not test-only. Attributing 20% to testing: ~$71/month.

Frequency	Test Cost	+ MWAA (20%)	Monthly Total
2x/week	$24	$71	$95
1x/day	$79	$71	$150
3x/day	$238	$71	$309
5x/day	$396	$71	$467
10x/day	$792	$71	$863

MiniStack monthly cost

MiniStack runs on a CI runner. No AWS charges.

Component	Cost
Docker container startup	~2 seconds
Test execution (41 infra tests)	~1 second
CI runner time (~2 min total)	$0.016 per run

Frequency	Runs/month	MiniStack Cost
2x/week	9	$0.14
1x/day	30	$0.48
3x/day	90	$1.44
5x/day	150	$2.40
10x/day	300	$4.80

Based on standard CI runner at $0.008/minute, 2 minutes per run.

Savings summary

Monthly savings (AWS → MiniStack)

Frequency	AWS/month	MiniStack/month	Saving	%
2x/week	$95	$0.14	$95	99.9%
1x/day	$150	$0.48	$150	99.7%
3x/day	$309	$1.44	$308	99.5%
5x/day	$467	$2.40	$465	99.5%
10x/day	$863	$4.80	$858	99.4%

Annual savings

Frequency	AWS/year	MiniStack/year	Annual Saving
2x/week	$1,140	$2	$1,138
1x/day	$1,800	$6	$1,794
3x/day	$3,708	$17	$3,691
5x/day	$5,604	$29	$5,575
10x/day	$10,356	$58	$10,298

Volume / performance testing (occasional)

These run against real AWS (not practical on a local emulator due to cluster scale):

Test	Rows	Glue Duration	Glue Cost	S3	Athena	Total
5M rows	5,100,000	~30 min	$2.20	$0.001	$0.02	$2.22
15M rows	15,000,000	~60 min	$4.40	$0.003	$0.05	$4.45
30M rows	30,000,000	~120 min	$8.80	$0.007	$0.11	$8.92

Running all three once per month: ~$16/month additional.

What runs where

Test Category	MiniStack	Real AWS	Cost Driver
DynamoDB schema + CRUD	Yes	Optional	DynamoDB: free-tier negligible
SSM parameter checks	Yes	Optional	SSM: free
S3 upload/download	Yes	Optional	S3: pennies
Glue ETL pipeline	No*	Yes	Glue: $2.64/run
Athena query validation	No*	Yes	Athena: pennies
MWAA DAG validation	Yes	Optional	MWAA: $353/mo fixed
Lambda function tests	Yes	Optional	Lambda: free tier covers it
SQS message flow	Yes	Optional	SQS: free tier covers it
Volume/perf tests	No	Yes	Glue at scale

MiniStack supports Glue catalog operations and Athena (via DuckDB), but running full PySpark ETL jobs locally requires additional setup (local Spark + Iceberg).

Quick start

1. Start MiniStack

# docker-compose.yml
services:
  ministack:
    image: ministackorg/ministack:latest
    ports:
      - "4566:4566"

docker compose up -d

2. Provision infrastructure

import boto3

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

ddb.create_table(
    TableName="my-table",
    KeySchema=[{"AttributeName": "pk", "KeyType": "HASH"}],
    AttributeDefinitions=[{"AttributeName": "pk", "AttributeType": "S"}],
    BillingMode="PAY_PER_REQUEST",
)

3. Point tests at MiniStack

# One config change — everything else stays the same
endpoint_url = os.environ.get("ENDPOINT_URL")  # None for real AWS

def make_client(service):
    kwargs = {}
    if endpoint_url:
        kwargs["endpoint_url"] = endpoint_url
        kwargs["aws_access_key_id"] = "test"
        kwargs["aws_secret_access_key"] = "test"
    return boto3.client(service, region_name="us-east-1", **kwargs)

# Real AWS
pytest tests/

# MiniStack
ENDPOINT_URL=http://localhost:4566 pytest tests/

4. Run in CI

# GitHub Actions example
jobs:
  integration-tests:
    runs-on: ubuntu-latest
    services:
      ministack:
        image: ministackorg/ministack:latest
        ports:
          - 4566:4566
    steps:
      - uses: actions/checkout@v4
      - run: pip install boto3 pytest
      - run: python scripts/provision.py  # Create tables, params, buckets
      - run: ENDPOINT_URL=http://localhost:4566 pytest tests/ -v

No AWS credentials. No IAM roles. No VPN. Every push, every PR.

Free tier reminder

If running against real AWS at low frequency, free tier covers most services:

Service	Free Tier	Covers test suite?
DynamoDB	25 GB + 25 RRU/WRU provisioned (always free)	On-demand mode: not covered, but cost is < $0.01/run
S3	5 GB + 20K GET + 2K PUT (12 months)	Yes
Lambda	1M requests + 400K GB-s (always free)	Yes
SQS	1M requests (always free)	Yes
SSM Standard	10K parameters + API calls (always free)	Yes
Glue	No free tier	Not covered — this is the cost
Athena	No free tier (but $0.001/run)	Negligible
MWAA	No free tier	$353/month minimum

Bottom line: Glue and MWAA are the only services that cost real money for testing. MiniStack eliminates the need for both in CI.

Services supported by MiniStack

55+ AWS services including: S3, DynamoDB, Lambda, SQS, SNS, SSM, Glue, Athena, MWAA, Step Functions, ECS, RDS, ElastiCache, Kinesis, EventBridge, Cognito, KMS, IAM, STS, Secrets Manager, CloudWatch, CloudFormation, API Gateway, Route53, EKS, ECR, and more.

Full list: github.com/ministackorg/ministack

Some tools paywall their services. MiniStack is MIT licensed. Free forever.

GitHub · Docker Hub · ministack.org · LinkedIn

All pricing verified against AWS published rates for 2025/2026. MiniStack is MIT-licensed open-source software. CI runner costs based on GitHub Actions standard runners at $0.008/minute.

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.