ministackorg/ministack

Free, open-source local AWS emulator. Free forever.

60+ AWS services on a single port · Multi-account & multi-region · Terraform compatible · Real databases · MIT licensed

Ministack.org · Docker Hub · LinkedIn

LocalStack recently moved its core services behind a paid plan. If you relied on LocalStack Community for local development and CI/CD pipelines, MiniStack is your free alternative.

• 60+ AWS services emulated on a single port (4566)
• Drop-in compatible — works with boto3, AWS CLI, Terraform, CDK, Pulumi, any SDK
• Multi-account & multi-region — a 12-digit access key becomes the account, the SigV4 region scopes the state; isolated tenants and regions on one endpoint, like real AWS
• Amazon Bedrock locally — Converse / InvokeModel with AWS-exact wire shapes; point MINISTACK_BEDROCK_PROXY_URL at Ollama, llama.cpp, or vLLM and get real completions through the Bedrock API
• Real infrastructure — RDS spins up actual Postgres/MySQL containers, ElastiCache spins up real Redis/Valkey, Athena runs real SQL via DuckDB (full image only), ECS runs real Docker containers
• Tiny footprint — ~270MB image, ~30MB RAM at idle vs LocalStack's ~1GB image and ~500MB RAM
• Fast startup — under 2 seconds, HTTP/2 (h2c) supported
• MIT licensed — use it, fork it, contribute to it

# Option 1: PyPI (simplest)
pip install ministack
ministack
# Runs on http://localhost:4566 — use GATEWAY_PORT=XXXX to change

# Option 2: Docker Hub
docker run -p 4566:4566 ministackorg/ministack

# Option 2b: Docker Hub with real infrastructure (RDS, ECS, Lambda containers)
docker run -p 4566:4566 -v /var/run/docker.sock:/var/run/docker.sock ministackorg/ministack

# Option 2c: Full image — Debian/glibc base with DuckDB (Athena), psycopg2, pymysql.
# Larger (~360 MB vs ~110 MB) but enables Athena and native PostgreSQL/MySQL drivers
# that don't ship musllinux wheels. Reports `edition: full` on /_ministack/health.
docker run -p 4566:4566 ministackorg/ministack:full

# Option 3: Clone and build
git clone https://github.com/ministackorg/ministack
cd ministack
docker compose up -d

# Verify (any option)
curl http://localhost:4566/_ministack/health

That's it. No account, no API key, no sign-up.

MiniStack exposes internal endpoints for test automation:

# Health check — returns service status
curl http://localhost:4566/_ministack/health

# Reset all state — wipe every service back to empty (useful between test runs)
curl -X POST http://localhost:4566/_ministack/reset

# Reset and re-run init scripts (boot.d + ready.d)
curl -X POST http://localhost:4566/_ministack/reset?init=1

# Runtime config — change service-level settings without restart
curl -X POST http://localhost:4566/_ministack/config \
  -H "Content-Type: application/json" \
  -d '{"lambda_svc.LAMBDA_EXECUTOR": "docker"}'

# Inspect emails sent via SES — returns every message grouped by account
curl http://localhost:4566/_ministack/ses/messages

# Filter by account (12-digit access-key ID used as the account ID)
curl "http://localhost:4566/_ministack/ses/messages?account=000000000000"

# Inspect SQS messages — returns every queue's messages grouped by account
# (includes Body, MessageId, ReceiveCount, VisibleAt, IsVisible, MessageAttributes, FIFO group/dedup)
curl http://localhost:4566/_ministack/sqs/messages

# Filter by account and/or a specific queue
curl "http://localhost:4566/_ministack/sqs/messages?account=000000000000&QueueUrl=http://localhost:4566/000000000000/my-queue"

# Inspect SMS sent via SNS Publish with a PhoneNumber — grouped by recipient
curl http://localhost:4566/_ministack/sns/sms-messages

# Filter by recipient, account and/or region
curl "http://localhost:4566/_ministack/sns/sms-messages?phoneNumber=%2B15551234567"

The reset endpoint is especially useful in CI pipelines and test suites — call it in setUp/beforeEach to get a clean environment for every test without restarting the container. Add ?init=1 to re-run your init scripts after the reset, restoring any resources they create (VPCs, queues, seed data, etc.).

The config endpoint supports these keys:

To set region or account ID, use environment variables at startup:

docker run -p 4566:4566 \
  -e MINISTACK_REGION=eu-west-1 \
  -e MINISTACK_ACCOUNT_ID=123456789012 \
  ministackorg/ministack

Or use the multi-tenancy feature — a 12-digit access key automatically becomes the account ID (see Multi-Tenancy below).

Also compatible with LocalStack's health endpoint:

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

MiniStack supports lightweight multi-tenancy without any configuration. If the AWS_ACCESS_KEY_ID is a 12-digit number, it is used as the Account ID for all ARN generation. Non-numeric keys (like test) fall back to the MINISTACK_ACCOUNT_ID env var or 000000000000.

# Team A — gets account 111111111111
export AWS_ACCESS_KEY_ID=111111111111
export AWS_SECRET_ACCESS_KEY=test
aws --endpoint-url=http://localhost:4566 sts get-caller-identity
# → { "Account": "111111111111", ... }

# Team B — gets account 222222222222
export AWS_ACCESS_KEY_ID=222222222222
export AWS_SECRET_ACCESS_KEY=test
aws --endpoint-url=http://localhost:4566 sts get-caller-identity
# → { "Account": "222222222222", ... }

All ARNs and resource state (SQS queues, Lambda functions, IAM roles, S3 buckets, DynamoDB tables, etc.) are fully isolated per account. Resources with the same name in different accounts never collide. This allows multiple developers or CI pipelines to share a single MiniStack endpoint with complete tenant isolation — no extra setup needed.

Since 1.4.0 state is additionally isolated per region — see Multi-Region below.

Terraform — set access_key in your provider block:

provider "aws" {
  access_key = "048408301323"
  secret_key = "test"
  region     = "us-east-1"
  endpoints { ... }
}

boto3 — pass aws_access_key_id:

boto3.client("s3",
    endpoint_url="http://localhost:4566",
    aws_access_key_id="048408301323",
    aws_secret_access_key="test",
)

Since 1.4.0, state is isolated per region as well as per account — no configuration needed. The region comes from the SigV4 credential scope (the region_name your SDK or --region your CLI is configured with), so two clients pointed at different regions see fully independent resources, exactly like real AWS:

# Same queue name, two regions — two independent queues
aws --endpoint-url=http://localhost:4566 --region us-east-1 sqs create-queue --queue-name jobs
aws --endpoint-url=http://localhost:4566 --region eu-west-1 sqs create-queue --queue-name jobs

aws --endpoint-url=http://localhost:4566 --region us-east-1 sqs list-queues
# → .../000000000000/jobs   (the us-east-1 queue)
aws --endpoint-url=http://localhost:4566 --region eu-west-1 sqs list-queues
# → .../000000000000/jobs   (a different queue — eu-west-1's)

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

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

use1.list_tables()["TableNames"]   # → ["users"]
euw1.list_tables()["TableNames"]   # → [] — eu-west-1 is independent

Region-isolated services: as of 1.5.3, every regional service is region-isolated except S3 and Aurora DSQL (the isolation migrations rolled out service by service from 1.4.0 to 1.4.12 — see the CHANGELOG for the per-release history; services introduced later, like AWS Config and the Cloud Control API in 1.4.14, were born region-scoped).

Cross-resource references resolve in the referenced ARN's own account and region (SNS→SQS fanout, EventBridge targets, event source mappings), and cross-region references that real AWS rejects return the same errors AWS returns — e.g. invoking a eu-west-1 Lambda from a us-east-1 Step Functions task fails with Functions from 'eu-west-1' are not reachable in this region, exactly as on AWS.

Not yet region-isolated: S3 and Aurora DSQL — these share state across regions within an account (as all services did before 1.4.0); use unique resource names there if your tests exercise two regions, until their isolation lands in a subsequent release. IAM/STS, CloudFront, Route 53, and Organizations are global services on AWS, so their account-scoped shared state is correct, not a gap.

Upgrading with PERSIST_STATE=1: existing state files load and migrate automatically (on-disk format v2 with a version stamp — a newer-format file is refused instead of mis-parsed on downgrade). Each record's region is recovered from its stored ARNs; legacy records that carry no ARN migrate to the default region (MINISTACK_REGION).

# Option A — environment variables (no profile needed)
export AWS_ACCESS_KEY_ID=test
export AWS_SECRET_ACCESS_KEY=test
export AWS_DEFAULT_REGION=us-east-1

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

# Option B — named profile (must pass --profile on every command)
aws configure --profile local
# AWS Access Key ID: test
# AWS Secret Access Key: test
# Default region: us-east-1
# Default output format: json

aws --profile local --endpoint-url=http://localhost:4566 s3 mb s3://my-bucket
aws --profile local --endpoint-url=http://localhost:4566 s3 cp ./file.txt s3://my-bucket/
aws --profile local --endpoint-url=http://localhost:4566 sqs create-queue --queue-name my-queue
aws --profile local --endpoint-url=http://localhost:4566 dynamodb list-tables
aws --profile local --endpoint-url=http://localhost:4566 sts get-caller-identity

chmod +x bin/awslocal
./bin/awslocal s3 ls
./bin/awslocal dynamodb list-tables

import boto3

# All clients use the same endpoint
def client(service):
    return boto3.client(
        service,
        endpoint_url="http://localhost:4566",
        aws_access_key_id="test",
        aws_secret_access_key="test",
        region_name="us-east-1",
    )

# S3
s3 = client("s3")
s3.create_bucket(Bucket="my-bucket")
s3.put_object(Bucket="my-bucket", Key="hello.txt", Body=b"Hello, MiniStack!")
obj = s3.get_object(Bucket="my-bucket", Key="hello.txt")
print(obj["Body"].read())  # b'Hello, MiniStack!'

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

# DynamoDB
ddb = client("dynamodb")
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": "u1"}, "name": {"S": "Alice"}})

# SSM Parameter Store
ssm = client("ssm")
ssm.put_parameter(Name="/app/db/host", Value="localhost", Type="String")
param = ssm.get_parameter(Name="/app/db/host")
print(param["Parameter"]["Value"])  # localhost

# Secrets Manager
sm = client("secretsmanager")
sm.create_secret(Name="db-password", SecretString='{"password":"s3cr3t"}')

# Kinesis
kin = client("kinesis")
kin.create_stream(StreamName="events", ShardCount=1)
kin.put_record(StreamName="events", Data=b'{"event":"click"}', PartitionKey="user1")

# EventBridge
eb = client("events")
eb.put_events(Entries=[{
    "Source": "myapp",
    "DetailType": "UserSignup",
    "Detail": '{"userId": "123"}',
    "EventBusName": "default",
}])

# Step Functions
sfn = client("stepfunctions")
sfn.create_state_machine(
    name="my-workflow",
    definition='{"StartAt":"Hello","States":{"Hello":{"Type":"Pass","End":true}}}',
    roleArn="arn:aws:iam::000000000000:role/role",
)

# Step Functions — TestState API (test a single state in isolation)
# Note: inject_host_prefix=False prevents boto3 from prepending "sync-" to the hostname
from botocore.config import Config as BotoConfig
sfn_test = client("stepfunctions", config=BotoConfig(inject_host_prefix=False))

result = sfn_test.test_state(
    definition='{"Type":"Pass","Result":{"greeting":"hello"},"End":true}',
    input='{"name":"world"}',
)
print(result["status"])  # SUCCEEDED
print(result["output"])  # {"greeting": "hello"}

# TestState with mock — test error handling without calling real services
result = sfn_test.test_state(
    definition=json.dumps({
        "Type": "Task",
        "Resource": "arn:aws:lambda:us-east-1:000000000000:function:my-fn",
        "Catch": [{"ErrorEquals": ["States.ALL"], "Next": "Fallback"}],
        "End": True
    }),
    input='{}',
    inspectionLevel="DEBUG",
    mock={"errorOutput": {"error": "ServiceError", "cause": "Timeout"}},
)
print(result["status"])  # CAUGHT_ERROR
print(result["nextState"])  # Fallback

# EC2
ec2 = client("ec2")
reservation = ec2.run_instances(
    ImageId="ami-00000001",
    MinCount=1,
    MaxCount=1,
    InstanceType="t3.micro",
)
instance_id = reservation["Instances"][0]["InstanceId"]
print(instance_id)  # i-xxxxxxxxxxxxxxxxx

# Security Groups
sg = ec2.create_security_group(GroupName="my-sg", Description="My SG")
ec2.authorize_security_group_ingress(
    GroupId=sg["GroupId"],
    IpPermissions=[{"IpProtocol": "tcp", "FromPort": 80, "ToPort": 80,
                    "IpRanges": [{"CidrIp": "0.0.0.0/0"}]}],
)

# VPC / Subnet
vpc = ec2.create_vpc(CidrBlock="10.0.0.0/16")
subnet = ec2.create_subnet(
    VpcId=vpc["Vpc"]["VpcId"],
    CidrBlock="10.0.1.0/24",
    AvailabilityZone="us-east-1a",
)

Supported Resource Types:

Unsupported resource types fail with CREATE_FAILED (or ROLLBACK_COMPLETE if rollback is enabled), so templates with unsupported types won't silently succeed.

MiniStack expands AWS SAM transforms (Transform: AWS::Serverless-2016-10-31) into native CloudFormation before provisioning, via the canonical aws-sam-translator. This ships in the full image only; a lean image that receives a SAM template returns a clear error pointing to the full image. See the IaC docs and MiniStack MCP for current guidance.

When you create an RDS instance, MiniStack starts a real database container and returns the actual connection endpoint:

import boto3
import psycopg2  # pip install psycopg2-binary

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"]
# Connect directly — it's a real Postgres instance
conn = psycopg2.connect(
    host=endpoint["Address"],   # localhost
    port=endpoint["Port"],      # 15432 (auto-assigned)
    user="admin",
    password="password",
    dbname="appdb",
)

Supported engines: postgres, mysql, mariadb, aurora-postgresql, aurora-mysql

Aurora cluster members share one cluster-owned database container, so SQL, users, and grants created through one member are visible through every member and through both cluster endpoints. The local reader endpoint intentionally resolves to the same read/write database process as the writer; writes sent to the reader are therefore accepted. Emulating an engine-enforced read-only reader would require a separate replicating database process. Deleting the final provisioned member leaves the cluster available but stops its shared container, so direct SQL and the Data API remain unavailable until a new member is created. That first new member restarts the preserved container and data; only DeleteDBCluster removes the container and its storage.

Each CreateCluster returns an ACTIVE cluster with an endpoint. Set DSQL_STRICT=1 to additionally spin up a real postgres:16-alpine container per cluster (capped by a fixed port window off DSQL_BASE_PORT, default 30 ports) behind an in-process Postgres wire-protocol proxy.

The proxy fails like real DSQL: SQL that DSQL rejects fails here too (serial columns, CREATE EXTENSION, TRUNCATE, temp tables, ALTER COLUMN TYPE, SET NOT NULL, materialized views, partitioned tables, ...), index creation is always asynchronous — plain CREATE INDEX is refused (unsupported mode. please use CREATE INDEX ASYNC.), as are CONCURRENTLY and USING — while expression index keys and partial indexes (WHERE predicate) are supported as long as the functions used are immutable (violations fail with 42P17 at submit, same as the backend; INCLUDE columns can't be expressions, the predicate can't hold a subquery), CREATE INDEX ASYNC and ALTER TABLE ASYNC ... VALIDATE CONSTRAINT return a job_id, sys.jobs / sys.wait_for_job are emulated (with the job id written literally or bound as $1; CALL sys.wait_for_job answers DSQL's succeeded column) (data that does not satisfy the constraint fails the job, not the submit — sys.jobs reports it failed with the violation as details), CHECK and FOREIGN KEY constraints via ALTER TABLE require NOT VALID and every other ADD CONSTRAINT form is refused, ADD COLUMN takes a name, a type and an optional STORAGE mode and nothing else, foreign keys are supported in full (all five referential actions, MATCH FULL/MATCH SIMPLE, deferrable — DEFERRABLE on any other kind of constraint is refused), ALTER TABLE ... DROP COLUMN works (several columns in one statement included) except on a primary key column, identity columns are bigint-only (CACHE 1 or ≥ 65536), index limits are enforced (8 key columns/index — checked before anything but CONCURRENTLY/USING, even the mode — 24/table), CREATE/ALTER/DROP STATISTICS work with DSQL's 5-per-table limit and statistics targets capped at 100 (ALTER TABLE ... SET STATISTICS is refused), dsql.enable_batched_nestloop defaults to on and takes only Boolean values, the rest of the dsql. prefix is reserved (42602), work_mem, statement_timeout and default_statistics_target can't be set, transactions allow only one DDL statement with no DDL+DML mixing, SELECT ... FOR UPDATE and FOR KEY SHARE are the only locking clauses supported (FOR SHARE and FOR NO KEY UPDATE are refused, at any nesting depth; the predicate itself is unrestricted), a transaction that outlives another session's DDL fails once with 40001 (OC001) and succeeds on retry, and the transaction limits (3,000 rows / 10 MiB / 5 min) are enforced.

CDC streams are metadata only: CreateStream validates its Kinesis target definition, enforces the 5-streams-per-cluster quota (ServiceQuotaExceededException) and reports ACTIVE right away, but no change record is ever delivered — a target whose Kinesis stream is absent (or, with AUTH=true, whose role cannot be assumed) lands FAILED with the service's statusReason code instead. Deleting a cluster deletes its streams.

GetCluster returns an endpoint of the form localhost:<port> (ports allocated from DSQL_BASE_PORT, default 25432). Any user/password is accepted — IAM auth tokens from generate_db_connect_auth_token work but aren't validated. Connect with e.g. psql "postgresql://admin@localhost:25432/postgres" and enter any test password when prompted (no TLS — use sslmode=disable/prefer; with psycopg2 use autocommit=True).

Both wire protocols are validated: the simple protocol (psql, psycopg2) and the extended Parse/Bind/Execute protocol used by pgjdbc, pgx, asyncpg, psycopg3 and every ORM built on prepared statements. Transaction state is read from the backend's ReadyForQuery status byte rather than inferred from statement text, so BEGIN/COMMIT sent over either protocol keeps the transaction rules accurate. A statement the proxy rejects inside a transaction aborts that block exactly as a real error would — later statements fail with 25P02 and COMMIT reports ROLLBACK.

Limitations: SQL analysis is heuristic regex, not a real parser (statement splitting, comment stripping and parenthesis matching are lexer-aware, but clause-level rules are pattern matches); the proxy's immutability check for index expressions and predicates is a denylist of well-known volatile functions — the backend catalog enforces the rest; transaction row counting is static (VALUES tuples only — INSERT ... SELECT/UPDATE/DELETE row counts aren't tracked); OC001 emulation is optimistic (catalog version bumps on forwarded DDL, not on successful commit); foreign keys are enforced by the backend, so a referencing write racing a change to the referenced key waits on a row lock instead of failing the loser with 40001 (OC000) the way DSQL's optimistic resolution does; the 1 KiB PK/index key-size limit is not enforced; and in a pipelined extended-protocol batch (several statements before one Sync) the rules that need to inspect backend state — the 24-index and 5-statistics limits and the primary-key DROP COLUMN check — are skipped; EXPLAIN output is Postgres-shaped, not DSQL's plan nodes (Full Scan (btree-table), Nested Loop (Batched Join), ...); dsql.* settings are Postgres placeholders, so they're missing from pg_settings; DSQL refuses more settings than the three listed above (only those were measured), while CREATE INDEX ASYNC is rejected as it is in multi-statement Q batches. Error messages match live Aurora DSQL where verified, otherwise Postgres-style approximations (0A000, 25006).

import boto3
import redis  # pip install redis

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

resp = ec.create_cache_cluster(
    CacheClusterId="my-redis",
    Engine="redis",
    CacheNodeType="cache.t3.micro",
    NumCacheNodes=1,
)

node = resp["CacheCluster"]["CacheNodes"][0]["Endpoint"]
r = redis.Redis(host=node["Address"], port=node["Port"])
r.set("key", "value")
print(r.get("key"))  # b'value'

A Redis sidecar is also always available at localhost:6379 when using Docker Compose.

Engine="valkey" works the same way — a real valkey/valkey container is spawned (versions 7.2, 8.0, 8.1), the default parameter group becomes default.valkey8, and the advertised endpoint speaks the same protocol (redis.Redis(...) connects unchanged).

Serverless caches are TLS-only and run in cluster mode, as on AWS: the keys of a multi-key command must share a hash slot. Trust MiniStack's ElastiCache CA and connect with TLS:

import time, urllib.request
ca = urllib.request.urlopen("http://localhost:4566/_ministack/elasticache/ca.pem").read().decode()
ec.create_serverless_cache(ServerlessCacheName="my-cache", Engine="valkey")
while (cache := ec.describe_serverless_caches(ServerlessCacheName="my-cache")["ServerlessCaches"][0])["Status"] == "creating":
    time.sleep(1)
ep = cache["Endpoint"]
r = redis.Redis(host=ep["Address"], port=ep["Port"], ssl=True, ssl_ca_data=ca)
r.ping()

Requires the full image (ministackorg/ministack:full). The default light image ships without DuckDB and returns mocked results — SELECT 1+1 will return 1, not 2.

Athena queries run via DuckDB and can query files in your local S3 data directory:

import boto3, time

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

# Query runs real SQL via DuckDB
resp = athena.start_query_execution(
    QueryString="SELECT 42 AS answer, 'hello' AS greeting",
    ResultConfiguration={"OutputLocation": "s3://athena-results/"},
)
query_id = resp["QueryExecutionId"]

# Poll for result
while True:
    status = athena.get_query_execution(QueryExecutionId=query_id)
    if status["QueryExecution"]["Status"]["State"] == "SUCCEEDED":
        break
    time.sleep(0.1)

results = athena.get_query_results(QueryExecutionId=query_id)
for row in results["ResultSet"]["Rows"][1:]:  # skip header
    print([col["VarCharValue"] for col in row["Data"]])
# ['42', 'hello']

Bedrock works out of the box with deterministic, family-aware mock responses — every field wire-shape-correct per model family (Anthropic, Titan, Nova, Llama, Mistral, Cohere, AI21), so SDK parsing and streaming code paths run unchanged.

Point MINISTACK_BEDROCK_PROXY_URL at any OpenAI-compatible /chat/completions endpoint (Ollama, llama.cpp, vLLM) and Converse / InvokeModel return real completions through the Bedrock API — prompts are translated to OpenAI shape, forwarded, and translated back to Bedrock shape. On connection error it falls back to the mock silently.

# Ollama on the host
docker run -p 4566:4566 \
  -e MINISTACK_BEDROCK_PROXY_URL=http://host.docker.internal:11434/ \
  ministackorg/ministack

bedrock = client("bedrock-runtime")
resp = bedrock.converse(
    modelId="anthropic.claude-3-5-sonnet-20240620-v1:0",
    messages=[{"role": "user", "content": [{"text": "Hello from MiniStack!"}]}],
)
print(resp["output"]["message"]["content"][0]["text"])

Note: token counts are a chars/4 heuristic — shape-correct, but don't assert on exact counts against the mock.

import boto3

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

ecs.create_cluster(clusterName="dev")

ecs.register_task_definition(
    family="web",
    containerDefinitions=[{
        "name": "nginx",
        "image": "nginx:alpine",
        "cpu": 128,
        "memory": 256,
        "portMappings": [{"containerPort": 80, "hostPort": 8080}],
    }],
)

# This actually runs an nginx container via Docker
resp = ecs.run_task(cluster="dev", taskDefinition="web", count=1)
task_arn = resp["tasks"][0]["taskArn"]

# Stop it (removes the container)
ecs.stop_task(cluster="dev", task=task_arn)

Each container also gets the standard ECS Task Metadata V4 endpoint injected as ECS_CONTAINER_METADATA_URI_V4, so anything inside the container that uses the AWS SDK for ECS metadata (X-Ray, OpenTelemetry, application code calling GET $ECS_CONTAINER_METADATA_URI_V4/task) works without changes. Alongside it, RunTask injects AWS_CONTAINER_CREDENTIALS_FULL_URI, AWS_CONTAINER_AUTHORIZATION_TOKEN, and AWS_ENDPOINT_URL so unmodified AWS SDKs running inside the task fetch emulated credentials from the new /v2/credentials/<uuid> endpoint and route service calls through MiniStack end-to-end without any client config.

Rolling (ECS) services pin tagged images to manifest digests per deployment, and UpdateService(forceNewDeployment=True) resolves them again. A task pulls its image on start and falls back to the local image when the pull fails, including images tagged with MiniStack ECR URIs, so services run offline. Private registry credentials come from repositoryCredentials.credentialsParameter (a Secrets Manager secret with username and password).

API Gateway v1/v2 HTTP proxy forwarding uses non-blocking event-loop semantics by offloading the upstream socket call to a worker thread. This preserves AWS-compatible response behavior while preventing long-running proxy calls from stalling unrelated requests (for example, parallel DynamoDB operations). The same non-blocking path is used for JWT JWKS fetches. Tune wall-clock limits with MINISTACK_APIGW_PROXY_TIMEOUT_SECONDS and MINISTACK_APIGW_JWKS_TIMEOUT_SECONDS at the bottom of the Configuration table above.

A Cognito token's iss is https://cognito-idp.<region>.amazonaws.com/<poolId>, exactly as on AWS. To let an unmodified client (Spring, Vault, aws-jwt-verify) follow it to MiniStack:

docker run -d --name ministack -p 443:4566 -p 4566:4566 -e USE_SSL=1 ministackorg/ministack
docker cp ministack:/tmp/ministack-tls/server.crt ./ministack-ca.pem

Then point the issuer host at MiniStack in /etc/hosts (127.0.0.1 cognito-idp.us-east-1.amazonaws.com) and trust ministack-ca.pem in your client's runtime. The OS keychain is not enough for these:

The generated certificate covers every region's issuer host. Lambda containers MiniStack starts get the hosts entries and the trust settings automatically. Remove the /etc/hosts line before calling the real Cognito.

The same certificate names the IoT DescribeEndpoint hosts, so an SDK can dial https://<endpointAddress>.

MiniStack supports two types of init scripts, with LocalStack-compatible paths:

Scripts from both paths are merged, deduplicated by filename, and run in alphabetical order. If the same filename exists in both paths, the MiniStack-native path takes priority.

Init scripts automatically receive AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_DEFAULT_REGION, and AWS_ENDPOINT_URL — no manual configuration needed. The aws CLI is bundled in the image.

Each script also gets:

This lets a script reference sibling files without hardcoding the mount path:

# ready.d/01-create-resources.sh
aws s3 mb s3://my-bucket
aws s3 cp "${MINISTACK_INIT_SCRIPT_DIR}/seed-data.json" 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"}')

Docker Compose — mount scripts at either path:

volumes:
  - ./init-scripts:/docker-entrypoint-initaws.d           # ministack-native
  # OR
  - ./init-scripts:/etc/localstack/init                    # localstack-compatible

Set ATHENA_ENGINE to control Athena's SQL execution engine. In auto mode, DuckDB is used if installed, otherwise queries return mock results.

Install DuckDB for full Athena SQL compatibility: pip install ministack[full].

When PERSIST_STATE=1, MiniStack saves service state to STATE_DIR on shutdown and reloads it on startup. Writes are atomic (write-to-tmp then rename) to prevent corruption on crash.

Services currently supporting persistence: All services — API Gateway v1/v2, ALB, ACM, AppConfig, AppSync, Athena, Aurora DSQL, Bedrock, Cloud Map, CloudFront, CloudWatch, CloudWatch Logs, CodeBuild, Cognito, DynamoDB, EC2, ECR, ECS, EFS, EKS, ElastiCache, EMR, EventBridge, EventBridge Scheduler, Firehose, Glue, IAM/STS, Kinesis, KMS, Lambda, MSK, RDS, Route 53, S3, Secrets Manager, SES, SES v2, SNS, SQS, SSM, Step Functions, Transfer Family, WAF v2

docker run -p 4566:4566 \
  -e PERSIST_STATE=1 \
  -e STATE_DIR=/data/ministack-state \
  -v /tmp/ministack-data:/data \
  ministackorg/ministack

Set LAMBDA_EXECUTOR=docker to run every Lambda invocation inside an AWS-supplied runtime container instead of a local subprocess. PackageType: Image always uses Docker regardless of this setting. With the default local executor, provided.* runs the deployment's bootstrap directly; the executable must be compatible with the MiniStack host's OS and architecture. Use the Docker executor for bootstraps that require the AWS runtime image.

Supported runtimes and the AWS public ECR images MiniStack pulls for them:

Containers are named lambda-<random-hex-16> and pooled across invocations. Idle containers are reaped after LAMBDA_WARM_TTL_SECONDS (default 300s) — no manual cleanup needed. The pool is also drained on /_ministack/reset.

Docker-in-Docker: when MiniStack itself runs inside a container (with the host Docker socket mounted), it detects that automatically and copies each Lambda's code into the sibling runtime container over the socket. No shared volume or extra configuration is required. The legacy LAMBDA_REMOTE_DOCKER_VOLUME_MOUNT env var is deprecated and ignored.

Networking: when MiniStack runs in Docker Compose, set DOCKER_NETWORK to the Compose network name. All container-backed services (Lambda, RDS, DSQL, EKS, ElastiCache) then attach to that network so Lambda code can reach MiniStack at http://<ministack-service-name>:4566. The legacy LAMBDA_DOCKER_NETWORK is still accepted (Lambda only) as a fallback.

Without a shared network, AWS_ENDPOINT_URL inside the Lambda container is rewritten from localhost to host.docker.internal, which only resolves out of the box on Docker Desktop. Lambda containers are therefore started with host.docker.internal mapped to host-gateway (as ECS and EKS containers already are), so a handler that calls back into MiniStack during its own invocation works on native Linux engines too. Passing your own --add-host host.docker.internal:... through LAMBDA_DOCKER_FLAGS overrides the mapping.

Example docker-compose.yml:

services:
  ministack:
    image: ministackorg/ministack:latest
    container_name: infra_ministack
    ports:
      - "4566:4566"
    environment:
      LAMBDA_EXECUTOR: docker
      DOCKER_NETWORK: ${COMPOSE_PROJECT_NAME}_infra-network
      AWS_DEFAULT_REGION: ${AWS_REGION:-eu-central-1}
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
    networks:
      - infra-network

networks:
  infra-network:

Lambda code in this setup should point at the MiniStack service name, not localhost:

boto3.client("s3", endpoint_url="http://infra_ministack:4566", ...)

If /var/run/docker.sock is root-owned on the host, add privileged: true to the ministack service so it can talk to the daemon.

RunInstances returns metadata by default — the right behaviour for CloudFormation and Terraform stacks full of AMI ids that never existed. Register an AMI backed by a container reference and launches against that id get a real box, so ssm:SendCommand can return a real exit code instead of always reporting success.

# 1. Register any image your daemon can resolve, local or from a registry
aws --endpoint-url=http://localhost:4566 ec2 register-image \
  --name my-box --image-location ghcr.io/you/my-box:1.0
# { "ImageId": "ami-0a1b2c3d4e5f60718" }

# 2. Launch it
aws --endpoint-url=http://localhost:4566 ec2 run-instances \
  --image-id ami-0a1b2c3d4e5f60718 --count 1 --instance-type t3.micro

# 3. DescribeInstances reports the container's address, and the box answers on it
aws --endpoint-url=http://localhost:4566 ec2 describe-instances

A locally built tag counts. The image is only pulled when the daemon does not already have it, so docker build -t my-box:dev . then registering my-box:dev needs no registry, no push and no credentials — which also means CI can build and launch an image without registry access. Rebuild the tag and the next RunInstances picks it up.

No configuration: registering an image is the opt-in. With nothing registered, EC2 never reaches for Docker at all, and an unregistered ami- id keeps launching the metadata-only record it always did. Both kinds of instance coexist in one account and region.

• Root device type: a container has no persistent root disk, so an AMI registered from a container reference is instance-store backed — no EBS root volume, and StopInstances / StartInstances are refused with UnsupportedOperation, exactly as AWS refuses them for an instance store-backed instance. RebootInstances restarts the container, TerminateInstances removes it, and a container that dies out of band reports terminated on the next DescribeInstances — a lost root disk is a lost instance. /_ministack/reset and shutdown sweep this MiniStack's instance containers, leaving any other MiniStack sharing the daemon alone.
• Snapshot-backed registration works too, because on AWS RegisterImage is metadata-only and never checks that the image can boot: import-snapshot then register-image registers as normal and reports ebs. There is simply nothing here to run, so the failure lands on RunInstances with InvalidAMIID.Unavailable rather than at registration.
• Addresses: the container's IP replaces the synthetic private and public addresses and both DNS names, so the guest is reachable from the shared Docker network.
• Failure: a container that cannot be created or started fails the RunInstances call and backs the instance and its IAM profile association out. A running record with nothing behind it is exactly what this exists to prevent. An image reference that cannot be pulled answers InvalidAMIID.Unavailable rather than a server error, since retrying it would fail identically.
• Guest contract: the image is launched with init as PID 1 and a sleep infinity keepalive appended, so an image that would otherwise exit immediately stays up. An image with its own ENTRYPOINT receives that as argv and is free to ignore it. An image with no shell is treated the way AWS treats an instance with no SSM agent: unmanaged, and Run Command refuses it.
• Registry rewrite: registered references route through MINISTACK_IMAGE_PREFIX like every other pulled image, so mirrored and airgapped setups work unchanged.

Divergences from AWS, stated plainly. ImageLocation carries a container reference rather than an S3 manifest path. A container is not a VM: there is no IMDS, no console output, no security-group enforcement or port publishing, no CreateImage from a running instance, and an attached EBS volume stays a record rather than appearing as a block device inside the guest. Container filesystems do not survive an emulator restart — restored instances report terminated, which is what AWS does when an instance store-backed instance loses its host. Terminated instances are also dropped from DescribeInstances after 60 seconds; AWS says only that a terminated instance "remains visible in the console for a short while", so a wait instance-terminated followed by a describe can find nothing where AWS would still answer.

MiniStack's EKS spawns a real k3s cluster (75 MB image) when you create a cluster. kubectl, Helm, and any Kubernetes tooling work out of the box.

# Local credentials for the AWS CLI. With AUTH=false any dummy key/secret
# works; kubectl's aws eks get-token plugin inherits these variables.
unset AWS_PROFILE AWS_SESSION_TOKEN
export AWS_ACCESS_KEY_ID=test
export AWS_SECRET_ACCESS_KEY=test
export AWS_DEFAULT_REGION=eu-central-1

# Create an EKS cluster — k3s starts automatically
aws --endpoint-url=http://localhost:4566 eks create-cluster \
  --name my-cluster --role-arn arn:aws:iam::000000000000:role/eks \
  --resources-vpc-config subnetIds=subnet-1

# Wait for k3s to finish booting so DescribeCluster includes its CA bundle.
aws --endpoint-url=http://localhost:4566 eks wait cluster-active --name my-cluster

# Generate a normal AWS EKS kubeconfig. k3s sends the aws eks get-token
# credential to MiniStack's authentication webhook.
aws --endpoint-url=http://localhost:4566 eks update-kubeconfig --name my-cluster

# Use kubectl against real Kubernetes (the default ~/.kube/config is updated)
kubectl get nodes          # Real k3s node, Ready status
kubectl create deployment nginx --image=nginx:alpine
kubectl get pods           # Real pod running

# Helm works too
helm repo add bitnami https://charts.bitnami.com/bitnami
helm install my-redis bitnami/redis --set auth.enabled=false

# Clean up — k3s container is removed automatically
aws --endpoint-url=http://localhost:4566 eks delete-cluster --name my-cluster

To enforce IAM, start MiniStack with AUTH=true (for example, AUTH=true python -m ministack, or add AUTH=true to the container environment). The root key/secret default to test/test; custom values must match the AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY of the MiniStack server. Under AUTH=true, create the IAM role before running the cluster example above:

aws --endpoint-url=http://localhost:4566 iam create-role \
  --role-name eks \
  --assume-role-policy-document \
  '{"Version":"2012-10-17","Statement":[{"Effect":"Allow","Principal":{"Service":"eks.amazonaws.com"},"Action":"sts:AssumeRole"}]}'

In strict mode, IAM policies govern EKS API calls such as DescribeCluster (needed by update-kubeconfig). Kubernetes access requires a separate grant: the principal that creates the cluster gets bootstrap administrator access unless --access-config bootstrapClusterCreatorAdminPermissions=false is supplied. The cluster's service role does not inherit that access. Other principals need an EKS Access Entry with kubernetesGroups bound through Kubernetes RBAC, or one of these EKS managed access policies:

Policies can use cluster or namespace scope. Namespace entries accept wildcard patterns such as dev-*; MiniStack reconciles their RBAC bindings when a matching namespace is created, and after association updates or deletions. EKS normally evaluates these policies in its control-plane authorizer. k3s has only Kubernetes RBAC, so MiniStack materializes equivalent, managed RBAC roles and bindings internally. User-supplied kubernetesGroups remain additive. Existing clusters without a recorded creator also need an explicit Access Entry.

With AUTH=false, neither IAM policies nor Access Entries restrict Kubernetes access. The CLI still needs credentials to generate its exec token, but MiniStack does not check their secret, registration, or permissions. Restart MiniStack to change AUTH; k3s caches authentication results for two minutes, the kube-apiserver default.

Note: EKS requires Docker socket access (-v /var/run/docker.sock:/var/run/docker.sock) to spawn k3s containers. The k3s image is pulled on first CreateCluster call.

Security trade-off: the k3s container is launched with --privileged. k3s server mode needs to remount /sys/fs/cgroup, which no granular Linux capability set permits — running unprivileged fails with failed to evacuate root cgroup. This grants the k3s container significant access on the Docker host. The trade-off is acceptable for local development against an emulator but should be considered before running MiniStack EKS on shared infrastructure. Omitting the Docker socket mount cleanly disables k3s and falls back to a static EKS mock.

MiniStack keeps Python, Node.js, and provided.* Lambda functions warm between invocations with the local executor. After the first call (cold start), the handler module or custom-runtime bootstrap stays alive in a persistent subprocess. Subsequent calls skip initialization, matching real AWS warm-start behaviour and making test suites significantly faster.

Custom runtimes receive each event through the Lambda Runtime API's long-polling /runtime/invocation/next endpoint, with a fresh request ID, deadline, and X-Ray trace header. Concurrent invocations lease separate workers; function updates and deletion invalidate the workers. A timeout or crashed bootstrap is discarded so the next invocation starts a fresh process. Durable invocations of a custom runtime retain the one-shot executor: a bootstrap's environment is fixed when the process starts, while Python and Node.js carry their per-call durable context in the event and stay on the warm pool. Docker, container-image, and proxy execution are unchanged.

MiniStack supports Node.js Lambda runtimes (nodejs14.x, nodejs16.x, nodejs18.x, nodejs20.x, nodejs22.x). Functions execute via a local node subprocess (or Docker when LAMBDA_EXECUTOR=docker) — no mocking, real JS execution.

import boto3, json, zipfile, io

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

code = "exports.handler = async (event) => ({ statusCode: 200, body: JSON.stringify(event) });"
buf = io.BytesIO()
with zipfile.ZipFile(buf, "w") as zf:
    zf.writestr("index.js", code)

lam.create_function(
    FunctionName="my-node-fn",
    Runtime="nodejs20.x",
    Role="arn:aws:iam::000000000000:role/r",
    Handler="index.handler",
    Code={"ZipFile": buf.getvalue()},
)

resp = lam.invoke(FunctionName="my-node-fn", Payload=json.dumps({"hello": "world"}))
print(json.loads(resp["Payload"].read()))  # {'statusCode': 200, 'body': '{"hello": "world"}'}

Layers that ship npm packages work too — MiniStack resolves the nodejs/node_modules subdirectory inside each layer zip and prepends it to the module search path.

MiniStack also sets the standard Lambda runtime environment before the handler module is loaded, including LAMBDA_TASK_ROOT, AWS_LAMBDA_FUNCTION_NAME, AWS_LAMBDA_FUNCTION_MEMORY_SIZE, and _LAMBDA_FUNCTION_ARN. That keeps import-time Lambda detection and conditional handler setup aligned with AWS warm runtime behaviour.

For languages AWS doesn't ship a runtime for (PHP, Deno, Bun, custom builds), point a function at your own running container instead of having MiniStack execute a deployment package. MiniStack forwards the Lambda event to that container as an HTTP POST and returns its JSON response as the function result.

The function is a real Lambda in MiniStack's registry — it has an ARN, shows up in list-functions, and works as a target for API Gateway AWS_PROXY integrations, EventBridge rules, SQS event sources, Step Functions tasks, and any other Lambda trigger. Only the execute hop is redirected.

Configure it per-function via the standard CreateFunction API:

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

lam.create_function(
    FunctionName="phpapi",
    Runtime="provided",                                # any value; ignored in proxy mode
    Role="arn:aws:iam::000000000000:role/r",
    Handler="index.handler",                           # any value; ignored in proxy mode
    Code={"ZipFile": b"PK\x05\x06" + b"\x00" * 18},    # empty zip stub
    Environment={"Variables": {
        "MINISTACK_LAMBDA_PROXY_URL": "http://host.docker.internal:9000/invoke",
    }},
)

Or globally via env var at startup: MINISTACK_LAMBDA_PROXY_<func-name>=http://....

Your container receives the Lambda event JSON as the request body. Reply with the function's response as JSON (or a Lambda Proxy response shape {"statusCode", "headers", "body"} if it sits behind API Gateway). MiniStack passes these context headers on every forward:

Errors map to Lambda's standard error shape so async-invoke retry, DLQ, destinations, and CloudWatch error metrics behave the same as for any other executor:

What this is not: AWS Lambda doesn't have a feature called "register an externally-running container as my function." If you want byte-for-byte parity in production, ship the same container as a Lambda container image (PackageType=Image) and use the AWS Lambda Runtime Interface inside it. Proxy mode is a local-dev shortcut for the inner-loop case; what your production code sees from MiniStack at the SDK boundary is identical to AWS, but the handler signature inside your container differs from a real Lambda runtime contract.

                    ┌──────────────────────────────────────────┐
 AWS CLI / boto3    │         ASGI Gateway  :4566              │
 Terraform / CDK ──►│  ┌────────────────────────────────────┐  │
 Any AWS SDK        │  │          Request Router            │  │
                    │  │  1. X-Amz-Target header            │  │
                    │  │  2. Authorization credential scope │  │
                    │  │  3. Action query param             │  │
                    │  │  4. URL path pattern               │  │
                    │  │  5. Host header                    │  │
                    │  │  6. Default → S3                   │  │
                    │  └────────────────┬───────────────────┘  │
                    │                 │                        │
                    │  ┌────────────────────────────────────┐  │
                    │  │   Service Handlers (lazy-loaded)   │  │
                    │  │                                    │  │
                    │  │  S3      SQS     SNS    DynamoDB   │  │
                    │  │  Lambda  IAM     STS    Secrets    │  │
                    │  │  SSM     Events  Kinesis    CW     │  │
                    │  │  CW Logs  SES    SESv2     ACM     │  │
                    │  │  Step Functions   API GW  v1/v2    │  │
                    │  │  ECS    RDS   ElastiCache  Glue    │  │
                    │  │  Athena   Firehose    Route53      │  │
                    │  │  Cognito  EC2    EMR   EBS  EFS    │  │
                    │  │  ALB/ELBv2   WAF v2   KMS  ECR     │  │
                    │  │  CloudFormation    CloudFront      │  │
                    │  │  AppSync  Cloud Map   CodeBuild    │  │
                    │  │  AutoScaling  AppConfig     EKS    │  │
                    │  │  RDS Data  S3 Files  Scheduler     │  │
                    │  │  Transfer Family   IoT Core        │  │
                    │  │  Bedrock (x4)   MSK                │  │
                    │  └────────────────────────────────────┘  │
                    │                                          │
                    │  In-Memory Storage + Optional Docker     │
                    └──────────────────────────────────────────┘
                                        │
                         ┌──────────────┼──────────────┐
                         ▼              ▼              ▼
                    Redis:6379    Postgres:15432+  MySQL:15433+
                    (ElastiCache)    (RDS)           (RDS)

# Install test dependencies
pip install boto3 pytest duckdb docker cbor2

# Start MiniStack
docker compose up -d

# Run the full test suite (5,700+ tests across all services)
pytest tests/ -v

Expected output:

tests/test_s3.py::test_s3_create_bucket PASSED
...
tests/test_lambda.py::test_lambda_invoke PASSED

1400+ passed in ~2 minutes

Works with both Terraform AWS Provider v5 and v6.

provider "aws" {
  region                      = "us-east-1"
  access_key                  = "test"
  secret_key                  = "test"
  s3_use_path_style           = true
  skip_credentials_validation = true
  skip_metadata_api_check     = true
  skip_requesting_account_id  = true

  endpoints {
    acm             = "http://localhost:4566"
    apigateway      = "http://localhost:4566"
    appsync         = "http://localhost:4566"
    athena          = "http://localhost:4566"
    bedrock         = "http://localhost:4566"
    bedrockagent    = "http://localhost:4566"
    cloudformation  = "http://localhost:4566"
    cloudfront      = "http://localhost:4566"
    cloudwatch      = "http://localhost:4566"
    codebuild       = "http://localhost:4566"
    cognitoidentity = "http://localhost:4566"
    cognitoidp      = "http://localhost:4566"
    dynamodb        = "http://localhost:4566"
    ec2             = "http://localhost:4566"
    ecr             = "http://localhost:4566"
    ecs             = "http://localhost:4566"
    efs             = "http://localhost:4566"
    elasticache     = "http://localhost:4566"
    elbv2           = "http://localhost:4566"
    emr             = "http://localhost:4566"
    events          = "http://localhost:4566"
    firehose        = "http://localhost:4566"
    glue            = "http://localhost:4566"
    iam             = "http://localhost:4566"
    kafka           = "http://localhost:4566"
    kinesis         = "http://localhost:4566"
    kms             = "http://localhost:4566"
    lambda          = "http://localhost:4566"
    logs            = "http://localhost:4566"
    rds             = "http://localhost:4566"
    route53         = "http://localhost:4566"
    s3              = "http://localhost:4566"
    s3control       = "http://localhost:4566"
    secretsmanager  = "http://localhost:4566"
    ses             = "http://localhost:4566"
    sesv2           = "http://localhost:4566"
    sns             = "http://localhost:4566"
    sqs             = "http://localhost:4566"
    ssm             = "http://localhost:4566"
    stepfunctions   = "http://localhost:4566"
    sts             = "http://localhost:4566"
    wafv2           = "http://localhost:4566"
  }
}

Terraform VPC module — fully supported (v6.6.0):

module "vpc" {
  source  = "terraform-aws-modules/vpc/aws"
  version = "6.6.0"

  name = "my-vpc"
  cidr = "10.0.0.0/16"

  azs             = ["us-east-1a", "us-east-1b", "us-east-1c"]
  private_subnets = ["10.0.0.0/20", "10.0.16.0/20", "10.0.32.0/20"]
  public_subnets  = ["10.0.64.0/20", "10.0.80.0/20", "10.0.96.0/20"]

  enable_nat_gateway = true
  single_nat_gateway = true
}

Creates VPC with per-VPC default network ACL, security group, and main route table. All 23 resources (subnets, IGW, NAT, route tables, associations, routes, default resources) supported.

Pin the generated apiId / REST API id to a caller-supplied value so URLs stay stable across terraform apply runs. Works on aws_apigatewayv2_api (HTTP + WebSocket) and aws_apigateway_rest_api.

resource "aws_apigatewayv2_api" "example" {
  name          = "example"
  protocol_type = "HTTP"
  tags = {
    ms-custom-id = "example"
  }
}
# → invoke URL stays "example.execute-api.localhost:4566" every apply

Duplicates in the same account fail with ConflictException. The LocalStack ls-custom-id tag is not recognised — use ms-custom-id only (callers hitting the old name get a clear BadRequestException).

Set AWS_ENDPOINT_URL to route all CDK requests to MiniStack:

export AWS_ENDPOINT_URL=http://localhost:4566
export AWS_ACCESS_KEY_ID=test
export AWS_SECRET_ACCESS_KEY=test
export AWS_DEFAULT_REGION=us-east-1

cdk bootstrap aws://000000000000/us-east-1
cdk deploy --require-approval never

Important: Running cdk deploy without AWS_ENDPOINT_URL will send requests to real AWS, not MiniStack. If you see "The security token included in the request is invalid", your requests are hitting AWS — set the endpoint.

To reset the bootstrap stack or delete all state:

# Delete a specific stack
aws --endpoint-url=http://localhost:4566 cloudformation delete-stack --stack-name CDKToolkit

# Or reset all MiniStack state
curl -X POST http://localhost:4566/_ministack/reset

# Pulumi.dev.yaml
config:
  aws:endpoints:
    - s3: http://localhost:4566
      dynamodb: http://localhost:4566
      # ... etc

MiniStack supports Amplify Gen 2 and CDK deployments. The underlying services are fully emulated:

• Auth — Cognito User Pools with JWKS/OIDC endpoints (/.well-known/jwks.json) for real JWT validation
• Data — AppSync GraphQL queries/mutations execute against DynamoDB resolvers (create/get/list/update/delete)
• Storage — S3
• Functions — Lambda (Python + Node.js)

export AWS_ENDPOINT_URL=http://localhost:4566
npx ampx sandbox

Note: AppSync supports Amplify-style CRUD operations. Advanced GraphQL features (fragments, unions, subscriptions) are not supported.

See Testcontainers/java-testcontainers, Testcontainers/go-testcontainers, and Testcontainers/python-testcontainers for ready-to-run integration tests using Testcontainers with the AWS SDK v2.

PRs welcome. The codebase is intentionally simple — each service is a single self-contained Python file in ministack/services/. Adding a new service means:

1. Create ministack/services/myservice.py with an async def handle_request(...) function and a reset() function
2. Add it to SERVICE_REGISTRY in ministack/app.py so the handler, aliases, and service filter are generated automatically
3. Add detection patterns to ministack/core/router.py
4. Add a fixture to tests/conftest.py and tests to tests/test_services.py

See CONTRIBUTING.md for a full walkthrough.

MIT — free to use, modify, and distribute. No restrictions.

Copyright (c) 2026 MiniStack Contributors

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.