fakecloud
Local AWS cloud emulator. Free forever.

fakecloud is a free, open-source local AWS emulator for integration testing and local development. It runs on a single port (4566), requires no account or auth token, and aims to faithfully replicate AWS behavior where it matters: real API compatibility, cross-service wiring, and test-friendly introspection.

Part of the faisca project family.

• Run your app against normal AWS SDKs, CLI tools, and IaC
• Stay fully local with no AWS account, no auth token, and no paid tier
• Assert what happened with first-party fakecloud SDKs for TypeScript, Python, Go, and Rust
• Test cross-service behavior like SES -> SNS/EventBridge, S3 -> SQS/SNS/Lambda/EventBridge, SQS -> Lambda, and DynamoDB Streams -> Lambda
• Use a fast single binary or Docker image, depending on your setup

In March 2026, LocalStack replaced its open-source Community Edition with a proprietary image that requires an account and auth token.

fakecloud exists for teams that want a fully local workflow with real AWS APIs, no sign-in step, and no paid wall around core development services. The SDKs build on top of that by making the /_fakecloud/* endpoints easier to use in tests; they are an extra layer, not the whole story.

Performance numbers measured on Apple M1: startup via time fakecloud, memory via ps -o rss after startup, binary size via ls -lh.

fakecloud now ships SDKs for the introspection and simulation API, so your tests can use normal AWS clients for application behavior and a fakecloud client for assertions and time control. They complement the main value proposition: a local AWS emulator you can run directly, compare against AWS behavior, and use without an account-gated platform in the middle.

Example test flow:

import { FakeCloud } from "fakecloud";

const fc = new FakeCloud("http://localhost:4566");

// Your app talks to fakecloud through the normal AWS SDK.
// Then your test can assert the side effects directly.
const { emails } = await fc.ses.getEmails();
expect(emails).toHaveLength(1);

await fc.reset();

Start fakecloud locally:

curl -fsSL https://raw.githubusercontent.com/faiscadev/fakecloud/main/install.sh | bash
fakecloud

cargo install fakecloud
fakecloud

git clone https://github.com/faiscadev/fakecloud.git
cd fakecloud
cargo run --release --bin fakecloud

docker run --rm -p 4566:4566 ghcr.io/faiscadev/fakecloud

To enable Lambda function execution, mount the Docker socket:

docker run --rm -p 4566:4566 -v /var/run/docker.sock:/var/run/docker.sock ghcr.io/faiscadev/fakecloud

# docker-compose.yml
services:
  fakecloud:
    image: ghcr.io/faiscadev/fakecloud
    ports:
      - "4566:4566"
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock # required for Lambda Invoke
    environment:
      FAKECLOUD_LOG: info

docker compose up

fakecloud is now listening at http://localhost:4566.

Point your usual AWS SDK or CLI at http://localhost:4566 with any dummy credentials, then use a fakecloud SDK when you want to inspect state or trigger background processors:

aws --endpoint-url http://localhost:4566 sqs create-queue --queue-name my-queue

22 AWS services, 1155 API operations:

Services talk to each other — this is the kind of behavior that matters in integration tests:

• SNS -> SQS/Lambda/HTTP: Fan-out delivery to all subscription types
• S3 -> SNS/SQS/Lambda/EventBridge: Bucket notifications on object create/delete
• EventBridge -> SNS/SQS/Lambda/Logs/Kinesis/StepFunctions/HTTP: Rules deliver to targets on schedule or event match, including API Destinations
• SQS -> Lambda: Event source mapping polls and invokes
• Kinesis -> Lambda: Event source mapping polls shards and invokes
• DynamoDB Streams -> Lambda: Event source mapping polls stream records and invokes
• DynamoDB -> Kinesis: Table changes stream to Kinesis Data Streams
• CloudWatch Logs -> Lambda/Kinesis/SQS: Subscription filters deliver log events
• Cognito -> Lambda: Pre-signup, post-confirmation, pre/post-auth, custom message, token generation, migration, and custom auth challenge triggers
• SES -> SNS/EventBridge: Email event fanout (send, delivery, bounce, complaint) via configured event destinations
• SES Inbound -> S3/SNS/Lambda: Receipt rules evaluate inbound email and execute S3, SNS, and Lambda actions
• Step Functions -> Lambda/SQS/SNS/EventBridge/DynamoDB: Task states invoke Lambda, send SQS messages, publish to SNS topics, put EventBridge events, and read/write DynamoDB items
• API Gateway v2 -> Lambda: HTTP API routes invoke Lambda functions with proxy integration v2.0 format
• CloudFormation -> Lambda/SNS: Custom resources invoke via ServiceToken, stack events notify via NotificationARNs
• SecretsManager -> Lambda: Rotation invokes Lambda for all 4 steps
• S3 Lifecycle: Background expiration and storage class transitions
• EventBridge Scheduler: Cron and rate-based rules fire on schedule

fakecloud is configured via CLI flags or environment variables.

# Examples
fakecloud --addr 127.0.0.1:5000 --log-level debug
FAKECLOUD_LOG=trace cargo run --bin fakecloud

curl http://localhost:4566/_fakecloud/health

{
  "status": "ok",
  "version": "0.8.1",
  "services": [
    "apigatewayv2",
    "bedrock",
    "cloudformation",
    "cognito-idp",
    "dynamodb",
    "elasticache",
    "events",
    "iam",
    "kinesis",
    "kms",
    "lambda",
    "logs",
    "rds",
    "s3",
    "secretsmanager",
    "ses",
    "sns",
    "sqs",
    "ssm",
    "states",
    "sts"
  ]
}

fakecloud exposes /_fakecloud/* endpoints for testing behaviors that AWS runs asynchronously (TTL expiration, scheduled rotation, etc.). Call these to advance time-dependent processes on demand.

fakecloud is organized as a Cargo workspace:

Protocol handling:

• Query protocol (SQS, SNS, IAM, STS, CloudFormation, SES v1, RDS, ElastiCache): form-encoded body, Action parameter, XML responses
• JSON protocol (SSM, EventBridge, DynamoDB, Secrets Manager, CloudWatch Logs, KMS, Cognito User Pools, Kinesis): JSON body, X-Amz-Target header, JSON responses
• REST protocol (S3, Lambda, SES v2, Bedrock, Bedrock Runtime): HTTP method + path-based routing, XML/JSON responses
• SES v1 inbound uses Query protocol for receipt rule/filter operations
• SigV4 signatures are parsed for service routing but never validated

fakecloud is verified two ways:

• Conformance checks AWS request/response shape and validation behavior
• E2E checks real behavior across services using the official AWS SDKs

For test code in your own app, the fakecloud SDKs provide a cleaner wrapper over the /_fakecloud/* endpoints for assertions, resets, and time-based processors.

cargo test --workspace              # unit tests
cargo build && cargo test -p fakecloud-e2e  # E2E tests (280+ tests)
cargo clippy --workspace -- -D warnings     # lint
cargo fmt --check                           # format check

E2E tests use the official aws-sdk-rust crates and spawn a real fakecloud server per test.

See ROADMAP.md for what's coming next: ECS, Elastic Load Balancing, CloudFront, and more.

Contributions are welcome.

1. Fork the repository
2. Create a feature branch: git checkout -b feat/my-feature
3. Follow existing conventions:
   • Conventional commits (feat:, fix:, chore:, test:, refactor:)
   • Per-action error enums with thiserror (no god enums)
   • Add E2E tests for new actions
4. Run the full test suite: cargo test --workspace
5. Open a pull request

fakecloud is a free, open-source local AWS emulator for integration testing and local development. For every service it implements, the goal is 100% behavioral parity with real AWS — measured by a schema-driven conformance harness that runs 54,334 / 56,694 generated test variants (95.8%) against official AWS Smithy models on every commit. 19 of 21 implemented services at 100%; Kinesis and Cognito Identity Provider in progress.

How conformance is measured. We commit AWS's own Smithy models to aws-models/ and generate inputs with six orthogonal strategies: boundary values from @length/@range constraints, exhaustive enum coverage, optional-field permutations, property-based random generation, examples from the model's @examples trait, and negative tests for each constraint. Every response is validated against the operation's Smithy output shape — missing required fields, unexpected fields, and wrong types are all failures. The baseline (conformance-baseline.json) is checked in CI: any regression blocks the merge. See crates/fakecloud-conformance/ for the harness and methodology. Reproduce locally with cargo run -p fakecloud-conformance -- run --services s3.

fakecloud is not a production-ready cloud replacement. It's not designed to be scalable or to handle production workloads. It's for testing — making sure your code works correctly before it hits the real cloud.

Known limitations:

• SNS email/SMS delivery: messages are recorded for introspection but not actually sent (no SMTP/SMS gateway). Use the /_fakecloud/sns/messages endpoint to verify delivery in tests.
• CloudWatch Logs anomaly detection: anomaly detectors are fully managed (CRUD), but no anomaly analysis runs. ListAnomalies returns empty.

Docker socket: Lambda, RDS, and ElastiCache require a Docker socket mount (/var/run/docker.sock) to run real containers. This grants the fakecloud process the ability to manage Docker containers on the host. Only use in development/testing environments.

License (AGPL-3.0): Using fakecloud as a dev/test tool has zero AGPL implications for your application. The AGPL copyleft clause only applies if you modify and redistribute fakecloud itself as a network service.

Add one of these snippets to your project so AI coding assistants (Claude Code, Cursor, GitHub Copilot) automatically use fakecloud for AWS integration tests.

## AWS Testing

For integration tests, use fakecloud as a local AWS emulator.

- Install: `curl -fsSL https://raw.githubusercontent.com/faiscadev/fakecloud/main/install.sh | bash`
- Run: `fakecloud` (listens on http://localhost:4566)
- Configure AWS SDK endpoint to http://localhost:4566 with dummy credentials (access_key=test, secret_key=test)
- Docs: https://fakecloud.dev/llms.txt

For AWS integration tests, use fakecloud (local AWS emulator) at http://localhost:4566.
Install: curl -fsSL https://raw.githubusercontent.com/faiscadev/fakecloud/main/install.sh | bash
Run: fakecloud
Use dummy credentials (access_key=test, secret_key=test).
Docs: https://fakecloud.dev/llms.txt

## AWS Testing

Use fakecloud as a local AWS emulator for integration tests.

- Run: `fakecloud` (listens on http://localhost:4566)
- Configure endpoint_url to http://localhost:4566 with dummy credentials
- Docs: https://fakecloud.dev/llms.txt

fakecloud is free and open-source software, licensed under the GNU Affero General Public License v3.0 (AGPL-3.0-or-later). Free for commercial use.

Built by faisca | fakecloud.dev