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, and SQS -> 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.
| Feature | fakecloud | LocalStack Community |
|---|---|---|
| License | AGPL-3.0 | Proprietary |
| Auth required | No | Yes (account + token) |
| Commercial use | Free | Paid plans only |
| Docker required | No (standalone binary) | Yes |
| Startup time | ~500ms | ~3s |
| Idle memory | ~10 MiB | ~150 MiB |
| Install size | ~19 MB binary | ~1 GB Docker image |
| AWS services | 15 | 30+ |
| Cognito User Pools | 80 operations | Paid only |
| SES v2 | 97 operations | Paid only |
| SES inbound email | Real receipt rule action execution | Stored but never executed |
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.
| Language | Install | Docs |
|---|---|---|
| TypeScript | npm install fakecloud |
sdks/typescript/README.md |
| Python | pip install fakecloud |
sdks/python/README.md |
| Go | go get github.com/faiscadev/fakecloud/sdks/go |
sdks/go/README.md |
| Rust | cargo add fakecloud-sdk |
crates/fakecloud-sdk |
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
fakecloudcargo install fakecloud
fakecloudgit clone https://github.com/faiscadev/fakecloud.git
cd fakecloud
cargo run --release --bin fakeclouddocker run --rm -p 4566:4566 ghcr.io/faiscadev/fakecloudTo 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: infodocker compose upfakecloud 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-queue18 AWS services, 990 API operations:
| Service | Actions | Highlights |
|---|---|---|
| S3 | 74 | Objects, multipart uploads, versioning, lifecycle, notifications, encryption, replication, website hosting |
| SQS | 20 | FIFO queues, dead-letter queues, long polling, batch operations, MD5 hashing |
| SNS | 34 | Fan-out to SQS/Lambda/HTTP, filter policies, platform applications |
| EventBridge | 57 | Pattern matching, scheduled rules, archives, replay, connections, API destinations |
| IAM | 128 | Users, roles, policies, groups, instance profiles, OIDC/SAML providers |
| STS | 8 | AssumeRole, session tokens, federation |
| SSM | 146 | Parameters, documents, commands, maintenance windows, associations, patch baselines |
| DynamoDB | 57 | Tables, items, transactions, PartiQL, backups, global tables, exports/imports |
| Lambda | 10 | Function CRUD, real code execution via Docker, event source mappings |
| Secrets Manager | 23 | Versioning, soft delete, rotation with Lambda, replication |
| CloudWatch Logs | 113 | Groups, streams, filtering, deliveries, transformers, query language, anomaly detection |
| KMS | 53 | Encryption, key management, aliases, grants, real ECDH and key import |
| CloudFormation | 8 | Template parsing, resource provisioning, custom resources via Lambda |
| SES | 111 | v2 (97 ops): identities, templates, configuration sets, contact lists, send email, suppression list, event destinations, DKIM/feedback/mail-from attributes, dedicated IP pools, account settings, import/export jobs, event fanout (SNS/EventBridge), mailbox simulator. v1 inbound (14 ops): receipt rule sets, receipt rules, receipt filters, inbound email pipeline with S3/SNS/Lambda actions |
| Cognito User Pools | 80 | User pools, app clients, users, groups, MFA, identity providers, resource servers, domains, devices, authentication flows, password management |
| Kinesis | 14 | Streams, records, shard iterators, retention changes, stream tagging |
| RDS | 10 | DB instances, engine/version discovery, orderable instance options, reboot, tagging |
| ElastiCache | 44 | Cache clusters, replication groups, global replication groups, serverless caches and snapshots, subnet groups, users/user groups, failover, tagging |
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
- EventBridge -> SNS/SQS/Lambda/Logs: Rules deliver to targets on schedule or event match
- S3 -> SNS/SQS/Lambda: Bucket notifications on object create/delete
- SQS -> Lambda: Event source mapping polls and invokes
- SecretsManager -> Lambda: Rotation invokes Lambda for all 4 steps
- 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
- CloudFormation -> Lambda: Custom resources invoke via ServiceToken
- 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.
| Flag | Env Var | Default | Description |
|---|---|---|---|
--addr |
FAKECLOUD_ADDR |
0.0.0.0:4566 |
Listen address and port |
--region |
FAKECLOUD_REGION |
us-east-1 |
AWS region to advertise |
--account-id |
FAKECLOUD_ACCOUNT_ID |
123456789012 |
AWS account ID |
--log-level |
FAKECLOUD_LOG |
info |
Log level (trace, debug, info, warn, error) |
FAKECLOUD_CONTAINER_CLI |
auto-detect | Container CLI to use (docker or podman) |
# Examples
fakecloud --addr 127.0.0.1:5000 --log-level debug
FAKECLOUD_LOG=trace cargo run --bin fakecloudcurl http://localhost:4566/_fakecloud/health{
"status": "ok",
"version": "0.5.1",
"services": ["cloudformation", "cognito-idp", "dynamodb", "elasticache", "events", "iam", "kinesis", "kms", "lambda", "logs", "rds", "s3", "secretsmanager", "ses", "sns", "sqs", "ssm", "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.
| Endpoint | Method | Description |
|---|---|---|
/_fakecloud/dynamodb/ttl-processor/tick |
POST | Expire DynamoDB items whose TTL attribute is in the past. Returns {"expiredItems": N}. |
/_fakecloud/secretsmanager/rotation-scheduler/tick |
POST | Rotate secrets whose rotation schedule is due. Returns {"rotatedSecrets": ["name", ...]}. |
/_fakecloud/s3/lifecycle-processor/tick |
POST | Run one S3 lifecycle processing tick. Returns {"processedBuckets": N, "expiredObjects": N, "transitionedObjects": N}. |
/_fakecloud/sqs/expiration-processor/tick |
POST | Expire SQS messages past retention period. Returns {"expiredMessages": N}. |
/_fakecloud/sqs/{queue_name}/force-dlq |
POST | Force-move messages exceeding maxReceiveCount to DLQ. Returns {"movedMessages": N}. |
/_fakecloud/events/fire-rule |
POST | Fire an EventBridge rule regardless of state. Body: {"busName": "...", "ruleName": "..."}. |
/_fakecloud/lambda/invocations |
GET | List all Lambda invocations (introspection). |
/_fakecloud/lambda/warm-containers |
GET | List all warm Lambda containers. Returns {"containers": [...]}. |
/_fakecloud/lambda/{function-name}/evict-container |
POST | Evict a warm Lambda container (forces cold start). Returns {"evicted": true/false}. |
/_fakecloud/rds/instances |
GET | List all fakecloud-managed RDS DB instances, including runtime metadata such as container id and mapped host port. |
/_fakecloud/sns/messages |
GET | List all published SNS messages. |
/_fakecloud/sns/pending-confirmations |
GET | List SNS subscriptions pending confirmation. Returns {"pendingConfirmations": [...]}. |
/_fakecloud/sns/confirm-subscription |
POST | Force-confirm an SNS subscription. Body: {"subscriptionArn": "..."}. Returns {"confirmed": true}. |
/_fakecloud/sqs/messages |
GET | List all SQS messages across queues. |
/_fakecloud/events/history |
GET | List all EventBridge events and deliveries. |
/_fakecloud/s3/notifications |
GET | List all S3 notification events. |
/_fakecloud/ses/emails |
GET | List all sent SES emails. |
/_fakecloud/ses/inbound |
POST | Simulate receiving an inbound email. Evaluates receipt rules and executes actions. |
/_fakecloud/cognito/confirmation-codes |
GET | List all pending confirmation codes across all pools and users. |
/_fakecloud/cognito/confirmation-codes/{pool_id}/{username} |
GET | Get confirmation codes for a specific user. |
/_fakecloud/cognito/confirm-user |
POST | Force-confirm a user. Body: {"userPoolId": "...", "username": "..."}. |
/_fakecloud/cognito/tokens |
GET | List all active access and refresh tokens (without exposing token strings). |
/_fakecloud/cognito/expire-tokens |
POST | Expire tokens. Body: {"userPoolId": "...", "username": "..."} (both optional). |
/_fakecloud/cognito/auth-events |
GET | List all auth events (sign-up, sign-in, failures, password changes). |
/_fakecloud/reset |
POST | Reset all state across all services. |
/_fakecloud/reset/{service} |
POST | Reset only the specified service's state. Returns {"reset": "service_name"}. |
fakecloud is organized as a Cargo workspace:
| Crate | Purpose |
|---|---|
fakecloud |
Binary entry point (clap CLI, Axum HTTP server) |
fakecloud-core |
AwsService trait, service registry, request dispatch, protocol parsing |
fakecloud-aws |
Shared AWS types (ARNs, error builders, SigV4 parser) |
fakecloud-sqs |
SQS implementation |
fakecloud-sns |
SNS implementation with delivery |
fakecloud-eventbridge |
EventBridge implementation with scheduler |
fakecloud-iam |
IAM and STS implementation |
fakecloud-ssm |
SSM Parameter Store implementation |
fakecloud-dynamodb |
DynamoDB implementation |
fakecloud-lambda |
Lambda implementation with Docker-based execution |
fakecloud-secretsmanager |
Secrets Manager implementation |
fakecloud-s3 |
S3 implementation |
fakecloud-logs |
CloudWatch Logs implementation |
fakecloud-kms |
KMS implementation |
fakecloud-cloudformation |
CloudFormation implementation |
fakecloud-ses |
SES implementation (v2 REST + v1 inbound Query) |
fakecloud-cognito |
Cognito User Pools implementation |
fakecloud-kinesis |
Kinesis implementation |
fakecloud-rds |
RDS implementation with Docker-backed database execution |
fakecloud-elasticache |
ElastiCache implementation with Docker-backed Redis execution |
fakecloud-e2e |
End-to-end tests using aws-sdk-rust |
Protocol handling:
- Query protocol (SQS, SNS, IAM, STS, CloudFormation, SES v1, RDS, ElastiCache): form-encoded body,
Actionparameter, XML responses - JSON protocol (SSM, EventBridge, DynamoDB, Secrets Manager, CloudWatch Logs, KMS, Cognito User Pools, Kinesis): JSON body,
X-Amz-Targetheader, JSON responses - REST protocol (S3, Lambda, SES v2): 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 checkE2E 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, API Gateway v2, and more.
Contributions are welcome.
- Fork the repository
- Create a feature branch:
git checkout -b feat/my-feature - 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
- Conventional commits (
- Run the full test suite:
cargo test --workspace - 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 — verified by 34,000+ automated conformance test variants against official AWS Smithy models across all API operations. 18 services, 100% conformance.
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.
Add one of these snippets to your project so AI coding assistants (Claude Code, Cursor, GitHub Copilot) automatically use fakecloud for AWS integration tests.
Claude Code — add to CLAUDE.md
## 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.txtCursor — add to .cursor/rules
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
GitHub Copilot — add to .github/copilot-instructions.md
## 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.txtfakecloud 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