Docs / Quick Start

Quick Start

Real examples with S3, DynamoDB, SQS, SNS, Lambda, and more. Each example is copy-paste ready.

S3: Object Storage

Create buckets, upload files, list objects.

$ awsemu s3 mb s3://my-bucket
make_bucket: my-bucket

$ echo "hello world" > myfile.txt
$ awsemu s3 cp myfile.txt s3://my-bucket/myfile.txt
upload: ./myfile.txt to s3://my-bucket/myfile.txt

$ awsemu s3 ls s3://my-bucket
2026-04-09 12:00:00  12 myfile.txt

$ awsemu s3 cp s3://my-bucket/myfile.txt downloaded.txt
$ cat downloaded.txt
hello world

Use case: Store file uploads, static assets, data lake files, backup archives. Test S3 event notifications with Lambda.

DynamoDB: NoSQL Database

Create tables, insert items, query data.

DynamoDB

$ awsemu dynamodb create-table \
    --table-name Users \
    --key-schema AttributeName=id,KeyType=HASH \
    --attribute-definitions AttributeName=id,AttributeType=S \
    --billing-mode PAY_PER_REQUEST
TableStatus: ACTIVE

$ awsemu dynamodb put-item --table-name Users \
    --item '{"id":{"S":"u001"},"name":{"S":"Tarek"},"role":{"S":"Admin"}}'

$ awsemu dynamodb get-item --table-name Users \
    --key '{"id":{"S":"u001"}}'
{"Item": {"id": {"S": "u001"}, "name": {"S": "Tarek"}, "role": {"S": "Admin"}}}

$ awsemu dynamodb scan --table-name Users

Use case: User sessions, shopping carts, leaderboards, IoT sensor data, real-time analytics. Test DynamoDB Streams with Lambda triggers.

SQS: Message Queues

Create queues, send and receive messages.

SQS

$ awsemu sqs create-queue --queue-name tasks
QueueUrl: http://sqs.us-east-1.localhost:4566/000000000000/tasks

$ awsemu sqs send-message \
    --queue-url http://sqs.us-east-1.localhost:4566/000000000000/tasks \
    --message-body "Process order #1234"
MessageId: abc123...

$ awsemu sqs receive-message \
    --queue-url http://sqs.us-east-1.localhost:4566/000000000000/tasks
Body: "Process order #1234"

Use case: Decouple microservices, async job processing, order pipelines, retry queues. Test SQS-triggered Lambda functions.

SNS: Pub/Sub Notifications

SNS

$ awsemu sns create-topic --name alerts
TopicArn: arn:aws:sns:us-east-1:000000000000:alerts

$ awsemu sns subscribe \
    --topic-arn arn:aws:sns:us-east-1:000000000000:alerts \
    --protocol email \
    --notification-endpoint dev@example.com

$ awsemu sns publish \
    --topic-arn arn:aws:sns:us-east-1:000000000000:alerts \
    --message "Server CPU above 90%"
MessageId: def456...

Use case: Alert systems, fan-out messaging, event-driven architectures. Connect SNS to SQS, Lambda, or HTTP endpoints.

Lambda: Serverless Functions

Create and invoke serverless functions. Requires Docker.

Lambda

# Create a handler
$ mkdir -p /tmp/fn && cat > /tmp/fn/handler.py << 'EOF'
def handler(event, context):
    name = event.get("name", "World")
    return {"statusCode": 200, "body": f"Hello, {name}!"}
EOF

$ cd /tmp/fn && zip function.zip handler.py

# Deploy
$ awsemu lambda create-function \
    --function-name hello \
    --runtime python3.12 \
    --handler handler.handler \
    --role arn:aws:iam::000000000000:role/role \
    --zip-file fileb://function.zip

# Wait for Active, then invoke
$ awsemu lambda invoke \
    --function-name hello \
    --payload '{"name":"Tarek"}' out.json
{
    "StatusCode": 200,
    "ExecutedVersion": "$LATEST"
}

$ cat out.json
{"statusCode": 200, "body": "Hello, Tarek!"}

Use case: API backends, event processing, cron jobs, data transformation. Test Lambda with S3 triggers, SQS triggers, API Gateway, Step Functions.

Secrets Manager

$ awsemu secretsmanager create-secret \
    --name db-credentials \
    --secret-string '{"username":"admin","password":"s3cure!"}'

$ awsemu secretsmanager get-secret-value --secret-id db-credentials
SecretString: {"username":"admin","password":"s3cure!"}

Use case: Database credentials, API keys, certificates. Test secret rotation, Lambda-based rotation functions.

ECS: Container Orchestration

ECS

$ awsemu ecs create-cluster --cluster-name production
clusterName: production

$ awsemu ecs list-clusters
arn:aws:ecs:us-east-1:000000000000:cluster/production

KMS: Encryption Keys

KMS

$ awsemu kms create-key --description "Encryption key"
KeyId: abc-123-def-456

$ awsemu kms list-keys

IAM: Identity & Access

IAM

$ awsemu iam create-user --user-name developer
$ awsemu iam create-role \
    --role-name lambda-role \
    --assume-role-policy-document '{"Version":"2012-10-17","Statement":[{"Effect":"Allow","Principal":{"Service":"lambda.amazonaws.com"},"Action":"sts:AssumeRole"}]}'
$ awsemu iam list-users

Persistence: Keep Your Data

By default, everything disappears when LocalEmu stops. Add PERSISTENCE=1 and your data survives restarts.

Persistence example

# Start with persistence
$ PERSISTENCE=1 localemu start

# Create a bucket and upload a file
$ awsemu s3 mb s3://persistent-bucket
$ echo "this data survives restarts" > data.txt
$ awsemu s3 cp data.txt s3://persistent-bucket/data.txt

# Stop and restart
$ localemu stop
$ PERSISTENCE=1 localemu start

# Your data is still there
$ awsemu s3 ls s3://persistent-bucket
2026-04-09 12:00:00  31 data.txt

$ awsemu s3 cp s3://persistent-bucket/data.txt -
this data survives restarts

This works for all services: DynamoDB tables, SQS queues, secrets, Lambda functions, everything. No paid tier required. See Configuration for snapshot strategies and storage details.

EC2: Virtual Machines

Create VPCs, security groups, and Docker-backed instances. Enable with EC2_VM_MANAGER=docker.

$ awsemu ec2 create-vpc --cidr-block 10.0.0.0/16
$ awsemu ec2 create-security-group --group-name web-sg --description "Web security group"
$ awsemu ec2 describe-vpcs
$ awsemu ec2 describe-security-groups

Use case: Test VPC configurations, security groups, user data scripts. With Docker backend: SSH into instances, run commands, test IMDS. See EC2 Reference for SSH, SSM, and security group details.

Running Modes

Start options

# Foreground (see the banner and logs)
$ localemu start

# Detached mode (runs in background)
$ localemu start -d
LocalEmu started (PID: 12345)

# Custom port
$ localemu start --port 4567

# Stop
$ localemu stop
LocalEmu stopped.

# Check status
$ localemu status

LocalEmu prevents running two instances on the same port. If port 4566 is already in use, you'll get a clear error with guidance. See CLI Reference for all commands and options.

← Installation awsemu CLI →