ministack README

The project's README from github.com/ministackorg/ministack. As one markdown file: README.md.

MiniStack — Free Open-Source AWS Emulator

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

GitHub release Build Docker Pulls Docker Image Size License Python

Ministack.org · Docker Hub · LinkedIn

Why MiniStack?

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.

Quick Start

# 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.

Internal API

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"

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:

Key Description
lambda_svc.LAMBDA_EXECUTOR Lambda execution mode (local or docker)
athena.ATHENA_ENGINE Athena query engine (duckdb or mock)
athena.ATHENA_DATA_DIR Directory for Athena DuckDB data files
stepfunctions._sfn_mock_config SFN mock config (AWS SFN Local compatible)
stepfunctions._SFN_WAIT_SCALE Scale factor for Wait state durations and retry sleeps (0 = skip all waits)

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

Multi-Tenancy

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.

Access Key Account ID Used
111111111111 111111111111
048408301323 048408301323
test 000000000000 (default)
AKIA_TEST_KEY_DO_NOT_USE 000000000000 (default)

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",
)

Multi-Region

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).

Using with AWS CLI

# 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

awslocal wrapper

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

Using with boto3

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 Services

Core Services

Service Operations Notes
S3 CreateBucket, DeleteBucket, ListBuckets, HeadBucket, PutObject, GetObject, DeleteObject, HeadObject, CopyObject, ListObjects v1/v2, DeleteObjects, GetBucketVersioning, PutBucketVersioning, GetBucketEncryption, PutBucketEncryption, DeleteBucketEncryption, GetBucketLifecycleConfiguration, PutBucketLifecycleConfiguration, DeleteBucketLifecycle, GetBucketCors, PutBucketCors, DeleteBucketCors, GetBucketAcl, PutBucketAcl, GetBucketTagging, PutBucketTagging, DeleteBucketTagging, GetBucketPolicy, PutBucketPolicy, DeleteBucketPolicy, GetBucketNotificationConfiguration, PutBucketNotificationConfiguration, GetBucketLogging, PutBucketLogging, ListObjectVersions, CreateMultipartUpload, UploadPart, CompleteMultipartUpload, AbortMultipartUpload, PutObjectLockConfiguration, GetObjectLockConfiguration, PutObjectRetention, GetObjectRetention, PutObjectLegalHold, GetObjectLegalHold, PutBucketReplication, GetBucketReplication, DeleteBucketReplication, GetObjectTagging, PutObjectTagging, DeleteObjectTagging Optional disk persistence via S3_PERSIST=1; Object Lock with retention & legal hold enforcement on delete; object tags are versioned (?tagging&versionId=… reads, writes, and deletes the per-version tag set); Multi-Region Access Points provision from CloudFormation (AWS::S3::MultiRegionAccessPoint) and <alias>.accesspoint.s3-global.amazonaws.com serves the member buckets through the regular S3 path
SQS CreateQueue, DeleteQueue, ListQueues, GetQueueUrl, GetQueueAttributes, SetQueueAttributes, PurgeQueue, SendMessage, ReceiveMessage, DeleteMessage, ChangeMessageVisibility, ChangeMessageVisibilityBatch, SendMessageBatch, DeleteMessageBatch, TagQueue, UntagQueue, ListQueueTags Both Query API and JSON protocol; FIFO queues with deduplication; DLQ support
SNS CreateTopic, DeleteTopic, ListTopics, GetTopicAttributes, SetTopicAttributes, Subscribe, Unsubscribe, ListSubscriptions, ListSubscriptionsByTopic, GetSubscriptionAttributes, SetSubscriptionAttributes, ConfirmSubscription, Publish, PublishBatch, TagResource, UntagResource, ListTagsForResource, CreatePlatformApplication, ListPlatformApplications, GetPlatformApplicationAttributes, SetPlatformApplicationAttributes, CreatePlatformEndpoint, GetEndpointAttributes, SetEndpointAttributes, DeleteEndpoint, DeletePlatformApplication SNS→SQS fanout delivery; SNS→Lambda fanout (asynchronous delivery); FIFO topics with 5-minute deduplication, sequence numbers, content-based deduplication, and subscription validation; mobile-push endpoint lifecycle with device-token dedup and Publish to platform-endpoint TargetArn
DynamoDB CreateTable, UpdateTable, DeleteTable, DescribeTable, ListTables, PutItem, GetItem, DeleteItem, UpdateItem, Query, Scan, BatchWriteItem, BatchGetItem, TransactWriteItems, TransactGetItems, DescribeTimeToLive, UpdateTimeToLive, DescribeContinuousBackups, UpdateContinuousBackups, DescribeEndpoints, TagResource, UntagResource, ListTagsOfResource, EnableKinesisStreamingDestination, DisableKinesisStreamingDestination, DescribeKinesisStreamingDestination, UpdateKinesisStreamingDestination TTL enforced via thread-safe background reaper (60s cadence); DynamoDB Streams — StreamSpecification emits INSERT/MODIFY/REMOVE records on all write operations, respects StreamViewType; Kinesis streaming destinations (aws_dynamodb_kinesis_streaming_destination) fan item mutations out into any Kinesis stream by ARN while the destination is ACTIVE
DynamoDB Streams ListStreams, DescribeStream, GetShardIterator, GetRecords Reads records emitted by the main DynamoDB service via boto3.client("dynamodbstreams") — single

ministack (ministackorg/ministack)

Searching Database…

5K ·GitHub
Ministack
What is this?MiniStack is a free, open-source local emulator for AWS that lets you run over 60 AWS services on your machine for development and testing.
Is this a library I import, or a standalone service I run?It's a standalone server you run (via Docker), exposing all 60+ AWS services on a single port (4566) that your code talks to using normal AWS SDKs or the CLI.
How do I get it running?Run the Docker image and point your AWS SDK, CLI, or Terraform provider at the exposed endpoint; no account or API key is needed.
Do I need Docker, or can I just run the Python code directly?The project ships as a Docker image (with docker-compose support) and is built in Python, so Docker is the expected way to run it.
Are all AWS services fully isolated and region-aware?Most regional services got per-region state isolation by version 1.5.3, but S3 and Aurora DSQL still share state across regions within an account, so you need unique resource names there if testing multiple regions.
Why was MiniStack created instead of just using LocalStack?LocalStack moved its core services behind a paid plan, so MiniStack was built as a free, MIT-licensed alternative for local development and CI/CD pipelines.
Does it use real databases instead of mocks?Yes — RDS spins up actual Postgres/MySQL containers, ElastiCache uses real Redis/Valkey, Athena runs real SQL via DuckDB, and ECS runs real Docker containers.
Can multiple developers or CI jobs share one MiniStack instance safely?Yes, through built-in multi-tenancy: a 12-digit AWS access key automatically becomes the account ID, fully isolating resources and state per account and per region with no extra setup.
Can I run local LLMs through the Bedrock API?Yes — pointing MINISTACK_BEDROCK_PROXY_URL at Ollama, llama.cpp, or vLLM lets you get real completions through MiniStack's AWS-exact Bedrock wire shapes.
What are similar projects?floci, awesome-aws, localstack, encore, laradock, full-stack-data-engineering, forge, seaweedfs
Which topics is it in?dynamodb, ec2, lambda, terraform, emulator, s3, devtools, aws, mysql, redis, testing, postgresql
Creator
ministackorg
Size
17.8 MB
Stars
5K
Updated
CommitOct 16Releasev1.5.28Oct 16
Age
6mo
Commits · 90 Days