MicroStack

A lightweight local AWS service emulator. Runs 39 AWS services on a single port, allowing you to build and test AWS integrations without connecting to the cloud.

Ported from MiniStack (Python) to .NET 10 / C#.

Why MicroStack?

• 39 AWS services emulated on a single port (4566)
• Native AOT — single self-contained binary, ~30MB container image, sub-second startup
• .NET Aspire integration — first-class AddMicroStack() resource for Aspire app models
• In-process testing — run inside WebApplicationFactory for sub-millisecond test times
• Multi-tenant — 12-digit access keys give each team/pipeline isolated resources
• MIT licensed — free forever

Packages

Package	Description
MicroStack.Aspire.Hosting	.NET Aspire hosting integration — adds MicroStack as a container resource

Quick Start

Docker:

docker run -p 4566:4566 ghcr.io/damianh/microstack:latest

From source:

dotnet run --project src/MicroStack/MicroStack.csproj

Verify:

curl http://localhost:4566/_microstack/health

Admin UI

MicroStack includes a web UI on the same gateway port:

• AWS/API endpoint: http://localhost:4566
• UI endpoint: http://localhost:4566/ui/

An unsigned browser navigation to http://localhost:4566/ redirects to /ui/. SDK, signed, presigned, and non-HTML root requests retain AWS behavior.

Local builds include the browser client's static assets. Native publishing builds the client separately. The client keeps its browser-wasm runtime identifier even when restore is invoked with the server's native runtime identifier.

The UI includes:

• Services — a searchable directory of all supported services
• Resource Explorer — read-only, account-aware inspection of retained resources, configuration, content, and configured connections
• Overview — service health, resource counts, and the global reset control
• Request Log — recent AWS API calls (service, action, account, status, duration)

For the separate, synthetic design reference (not the running Admin UI), see the Resource Explorer prototype.

Usage

Point any AWS SDK client at http://localhost:4566:

var config = new AmazonSQSConfig
{
    ServiceURL = "http://localhost:4566",
};

var client = new AmazonSQSClient(
    new BasicAWSCredentials("test", "test"), config);

await client.CreateQueueAsync("my-queue");

See the Getting Started guide for more examples.

Aspire Integration

dotnet add package MicroStack.Aspire.Hosting

var builder = DistributedApplication.CreateBuilder(args);

var microstack = builder.AddMicroStack("microstack")
    .WithDataVolume()                    // persistent state across restarts
    .WithServices("s3,sqs,dynamodb")     // limit enabled services
    .WithRegion("eu-west-1");            // set AWS region

builder.AddProject<Projects.MyApi>("api")
    .WithReference(microstack);

builder.Build().Run();

See Integration Testing for Aspire-based test patterns.

Supported Services

Category	Services
Compute & Serverless	Lambda, Step Functions, ECS, EMR
Storage	S3, EFS
Database	DynamoDB, RDS, RDS Data API, ElastiCache
Messaging	SQS, SNS, EventBridge, Kinesis, Firehose
Networking	EC2, Route 53, CloudFront, ALB, API Gateway (v1+v2), Service Discovery
Security	IAM, STS, KMS, ACM, Cognito (IdP + Identity), WAF v2, Secrets Manager
Management	CloudFormation, CloudWatch (Logs + Metrics), SSM Parameter Store, AppSync
Other	SES, ECR, Glue, Athena

See Services Overview for the full list of supported operations per service.

Internal API

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

# Reset all state — useful between test runs
curl -X POST http://localhost:4566/_microstack/reset

# Runtime config — change settings without restart
curl -X POST http://localhost:4566/_microstack/config \
  -H "Content-Type: application/json" \
  -d '{"stepfunctions._sfn_mock_config": "{...}"}'

See Internal API for full details.

Configuration

Variable	Default	Description
GATEWAY_PORT	4566	Port to listen on
MICROSTACK_HOST	localhost	Hostname for URL generation
MICROSTACK_REGION	us-east-1	Default AWS region
MICROSTACK_ACCOUNT_ID	000000000000	Default AWS account ID
PERSIST_STATE	0	Set to 1 for JSON state persistence
STATE_DIR	<temp>/microstack-state	Directory for persisted state
SERVICES	(all)	Comma-separated list of services to enable

See Configuration for all options including S3 persistence, service aliases, and Docker Compose examples.

Multi-Tenancy

Use a 12-digit AWS access key to simulate separate accounts:

var client1 = new AmazonSQSClient(new BasicAWSCredentials("111111111111", "test"), config);
var client2 = new AmazonSQSClient(new BasicAWSCredentials("222222222222", "test"), config);
// Each account has fully isolated resources

See Multi-Tenancy for details.

Docker

services:
  microstack:
    image: ghcr.io/damianh/microstack:latest
    ports:
      - "4566:4566"
    environment:
      - PERSIST_STATE=1
    volumes:
      - microstack-state:/tmp/microstack-state

volumes:
  microstack-state:

See Docker for more options.

MicroStack also supports generic Testcontainers clients with random port mappings. Runnable .NET, Java, Go, Python, and TypeScript examples are included under examples/testcontainers.

Using with AWS CLI

export AWS_ACCESS_KEY_ID=test
export AWS_SECRET_ACCESS_KEY=test

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

See AWS CLI for profiles and more examples.

License

MIT

Acknowledgements

MicroStack is a .NET port of MiniStack, a Python-based local AWS service emulator.