cloudmock

CloudMock

Local AWS emulation with built-in observability.

100 AWS services + distributed tracing + error tracking + alerting — in one binary. Language-agnostic via OpenTelemetry.

Quick Start

npx cloudmock
# or
brew install viridian-inc/tap/cloudmock
# or
sudo snap install cloudmock
# or
docker run -p 4566:4566 -p 4500:4500 ghcr.io/viridian-inc/cloudmock:latest

Point your AWS SDK:

export AWS_ENDPOINT_URL=http://localhost:4566

Open DevTools at http://localhost:4500

Why CloudMock?

• 100 AWS services emulated locally — no AWS account needed
• Full observability — traces, metrics, logs, and errors in one dashboard
• Language-agnostic — works with any OpenTelemetry SDK (Go, Python, Java, Node, Rust, ...)
• Built-in DevTools — topology maps, request tracing, chaos engineering
• State snapshots — export state to JSON, commit to git, restore on startup — everyone shares the same baseline
• MIT licensed — free to use, modify, distribute, and embed

Usage

CloudMock is a drop-in replacement for AWS. Point any SDK at localhost:4566:

// Node.js
const client = new S3Client({
  endpoint: "http://localhost:4566",
  region: "us-east-1",
  credentials: { accessKeyId: "test", secretAccessKey: "test" },
  forcePathStyle: true,
});

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

// Go
cfg, _ := config.LoadDefaultConfig(ctx,
    config.WithBaseEndpoint("http://localhost:4566"))

Install

Services

100 AWS services including S3, DynamoDB, SQS, SNS, Lambda, API Gateway, Cognito, EC2, ECS, EKS, EventBridge, IAM, KMS, RDS, Route 53, Step Functions, and many more.

See the full list at cloudmock.app/docs/services.

Performance

CloudMock is the fastest AWS mock available — 249x faster than LocalStack, 143x faster than Moto.

Test Mode

For CI and test suites, test mode strips all observability overhead and uses a Rust-accelerated DynamoDB store. Only the gateway runs — no dashboard, no admin API, no tracing:

CLOUDMOCK_TEST_MODE=true npx cloudmock  # 0.1s startup, 0.009ms per operation

Benchmarks (requests/sec — 200 concurrent, 30s sustained)

Gatling gun tests using hey. All three running on the same machine.

Geometric mean: CloudMock 163,224 req/s — 250x faster than Moto (654 req/s), 162x faster than LocalStack (1,007 req/s).

cm := sdk.New()
cfg := cm.Config()
client := dynamodb.NewFromConfig(cfg) // 43ns per GetItem, 0 allocs

Developer Time Saved

How much wait time CloudMock eliminates vs LocalStack (20-25 test runs/day, 6 min saved per run):

At 0.5ms per operation, tests feel instant. No context switching, no waiting, no tab-switching while your suite runs.

What makes CloudMock fast

• Frozen JSON cache — items pre-serialized to JSON at write time; reads return cached bytes with zero marshaling (43ns, 0 allocs)
• Go + fasthttp — native binary, zero-copy request handling, no interpreter overhead
• Rust-accelerated DynamoDB — hot-path PutItem/GetItem via Rust shared library with serde_json + DashMap
• Direct partition lookup — O(1) hash key resolution from KeyConditionExpression, limit pushdown to B-tree
• String-interned keys — sync.Map intern pool eliminates repeat allocations for partition key lookups
• Pre-serialized XML — all 19 XML services serialize to RawBody at handler level, bypassing gateway marshal
• goccy/go-json everywhere — 2-3x faster than encoding/json across all 73 JSON services
• Lock-free SQS — atomic counter UUID/receipt generation, no crypto/rand syscall per message
• Test mode — fasthttp server, all observability stripped, 100 services pre-resolved into plain map

Full benchmark details and methodology

SDKs

CloudMock provides native SDK adapters for every major language:

Every SDK auto-starts the CloudMock binary, returns pre-configured AWS clients, and cleans up on exit. One line of code to start testing:

# Python
with mock_aws() as cm:
    s3 = cm.boto3_client("s3")

// Node.js
const cm = await mockAWS();
const s3 = new S3Client(cm.clientConfig());

// Java
try (var cm = CloudMock.start()) {
    var s3 = S3Client.builder().endpointOverride(cm.endpoint()).build();
}

// Go (in-process — zero network, 20μs/op)
cm := sdk.New()
s3Client := s3.NewFromConfig(cm.Config())

GitHub Action

One line to add CloudMock to your CI:

- uses: viridian-inc/cloudmock-action@v1

Auto-installs, starts in test mode (135x faster than LocalStack), health-checks, and sets AWS_ENDPOINT_URL for all subsequent steps. Works with Node.js, Python, Go, Java, Rust, and any language with an AWS SDK.

To disable test mode and get full observability in CI:

- uses: viridian-inc/cloudmock-action@v1
  with:
    test-mode: 'false'

Create a Project

npx create-cloudmock-app my-app

Generates a complete project with CloudMock pre-configured for your stack. Supports Node.js, Python, Go, Java, and Rust with S3, DynamoDB, and SQS templates.

Docker Compose Stacks

Eight ready-to-run stacks in docker/stacks/:

cd docker/stacks/minimal
docker compose up

See the Docker Compose guide for quick starts, customization, and how to add your own services.

Switching from LocalStack or Moto?

• Migrate from LocalStack — 5-minute step-by-step
• Migrate from Moto — Python pytest/unittest migration

Traffic Recording & Replay

Record real AWS traffic and replay against CloudMock to validate compatibility:

cloudmock record --output prod-traffic.json    # proxy mode: captures real AWS calls
cloudmock validate --input prod-traffic.json   # replay + compare, exit 0 = all match

CloudTrail Event Replay

Recreate production AWS state from CloudTrail audit logs:

# Export CloudTrail events from AWS
aws cloudtrail lookup-events --start-time 2026-03-01 --output json > trail.json

# Replay write operations against CloudMock
cloudmock cloudtrail replay --input trail.json --endpoint http://localhost:4566

Filter by service, control replay speed, or use the admin API:

cloudmock cloudtrail replay --input trail.json --services dynamodb,s3 --speed 0
curl -X POST http://localhost:4599/api/cloudtrail/replay -d @trail.json

Comparison

Documentation

Full docs at cloudmock.app

Community

• GitHub Issues — bugs and feature requests
• GitHub Discussions — questions and ideas

License

CloudMock is licensed under the MIT License. See LICENSE.

Copyright 2026 Viridian Inc.