fakecloud
Local AWS cloud emulator. Free forever.
fakecloud is a free, open-source local AWS emulator for integration testing and local development. Single binary, no account, no auth token, no paid tier. Point your AWS SDK at http://localhost:4566 and it works.
In March 2026, LocalStack replaced its open-source Community Edition with a proprietary image that requires an account and auth token. fakecloud exists so teams can keep a fully local AWS testing workflow without one.
curl -fsSL https://raw.githubusercontent.com/faiscadev/fakecloud/main/install.sh | bash
fakecloudThen point any AWS SDK or CLI at http://localhost:4566 with dummy credentials:
aws --endpoint-url http://localhost:4566 sqs create-queue --queue-name my-queueOther install options (Cargo, Docker, Docker Compose, source) are documented at fakecloud.dev/docs/getting-started.
- Free, forever. AGPL-3.0, no paid tier, no account, no token.
- 100% conformance per implemented service. Every operation validated against AWS's own Smithy models — 59,000+ generated test variants on every commit.
- Tested against upstream Terraform acceptance tests. CI runs
hashicorp/terraform-provider-awsTestAcc*suites against fakecloud. Catches waiter/field-presence/drift bugs that pure SDK tests miss. - Real cross-service wiring. EventBridge -> Step Functions, S3 -> Lambda, SES inbound -> S3/SNS/Lambda, and 15+ more integrations actually execute end-to-end.
- Real infrastructure for stateful services. Lambda runs in Docker containers (23 runtimes). RDS runs real Postgres/MySQL/MariaDB/Oracle/SQL Server/Db2. ElastiCache runs real Redis/Valkey/Memcached.
- Single binary. ~19 MB, ~10 MiB idle memory, ~500ms startup. No Docker required to run fakecloud itself (only to exercise the services that need real containers).
- Bedrock, the whole surface. 111 operations across runtime + full control plane:
InvokeModel/Converse(with streaming), guardrails (real content evaluation + PII detection), custom model jobs, model import, inference profiles, provisioned throughput, async batch via S3, prompt management, agreements, automated reasoning. Configurable responses per prompt + fault injection for deterministic Bedrock tests. LocalStack's Ultimate-tier Bedrock covers 4 ops backed by Ollama; fakecloud is free and covers the full Bedrock shape. See/bedrock-emulator/. - First-party test SDKs for TypeScript, Python, Go, PHP, Java, and Rust. Assert on what your code called without writing raw HTTP.
- Opt-in SigV4 verification and IAM enforcement. Off by default so tests just work; turn on
--verify-sigv4for real cryptographic signature checking and--iam soft|strictfor identity-policy evaluation (Allow/Deny with Deny precedence, Action/Resource wildcards, user/group/role policies,Conditionblocks with all 28 AWS operators against global keys likeaws:username/aws:SourceIp/aws:CurrentTime, plus resource-based policies for S3 bucket, SNS topic, and Lambda function policies with AWS's cross-account combining semantics) across IAM, STS, SQS, SNS, and S3. See the security docs. - LocalStack and real-AWS URL compatibility. Both
*.localhost.localstack.cloudand*.amazonaws.comHost headers decode to service + region for routing, including every S3 virtual-hosted variant (<bucket>.s3.<region>.…, legacy<bucket>.s3.amazonaws.comwith implicitus-east-1, and the older dash-separated<bucket>.s3-<region>.amazonaws.com). Persisted queue URLs, presigned URLs, webhook targets, and dev scripts from either system replay against fakecloud unchanged.
33 services, 2,422 operations, 100% conformance per implemented service.
| Service | Ops | Notes |
|---|---|---|
| S3 | 107 | Versioning, lifecycle, notifications, multipart, replication, website, real SSE-KMS encrypt/decrypt |
| SQS | 23 | FIFO, DLQs, long polling, batch, real KMS encrypt/decrypt on KmsMasterKeyId queues |
| SNS | 42 | Fan-out to SQS/Lambda/HTTP, filter policies, KMS audit-trail on KmsMasterKeyId topics |
| EventBridge | 57 | Pattern matching, schedules, archives, replay, API destinations |
| EventBridge Scheduler | 12 | at/rate/cron, SQS targets, DLQ routing, one-shot self-delete |
| Lambda | 85 | Real Docker, 23 runtimes, ESM with FilterCriteria + partial-batch failure |
| DynamoDB | 57 | Transactions, PartiQL, backups, global tables, streams, KMS audit-trail on SSE-KMS tables |
| IAM | 176 | Users, roles, policies, groups, OIDC/SAML, PassRole trust enforcement |
| STS | 11 | AssumeRole, session tokens, federation |
| SSM | 146 | Parameters, documents, commands, maintenance, patch baselines, SecureString -> real KMS encrypt/decrypt |
| Secrets Manager | 23 | Versioning, rotation via Lambda, replication, real KMS encrypt/decrypt |
| CloudWatch Logs | 113 | Groups, streams, subscription filters, query language |
| KMS | 53 | Encryption, aliases, grants, real ECDH, key import, cross-service hook |
| CloudFormation | 90 | Template parsing, resource provisioning, custom resources |
| SES (v2 + v1 inbound) | 110 | Sending, templates, DKIM, real receipt rule execution |
| Cognito User Pools | 122 | Pools, clients, MFA, identity providers, full auth flows; verification email -> SES, SMS -> SNS, all 12 Lambda triggers |
| Kinesis | 39 | Streams, records, shard iterators, retention |
| RDS | 163 | Real Postgres, MySQL, MariaDB, Oracle, SQL Server, Db2 via Docker; lifecycle ops emit aws.rds EventBridge events; PostgreSQL aws_lambda + aws_s3 extensions and Aurora-compatible MySQL/MariaDB mysql.lambda_async/mysql.lambda_sync invoke fakecloud Lambda + import/export S3 objects from SQL |
| ElastiCache | 75 | Real Redis, Valkey, Memcached via Docker |
| Step Functions | 37 | Full ASL interpreter, Lambda/SQS/SNS/EventBridge/DynamoDB tasks |
| API Gateway v1 | 124 | REST APIs, resources, methods, integrations (MOCK/HTTP/HTTP_PROXY/AWS_PROXY Lambda), deployments, stages, API keys, usage plans, authorizers, models, request validators, VPC links, domain names, base path mappings, client certs, gateway responses, docs, tags |
| API Gateway v2 | 103 | HTTP APIs, routes, integrations, stages, deployments, authorizers, domains, models, VPC links, routing rules, developer portals, CORS, tags |
| Bedrock | 101 | Foundation models, guardrails, custom models, invocation/eval jobs |
| Bedrock Runtime | 10 | InvokeModel, Converse, streaming, configurable responses, fault inject |
| ECR | 58 | Full API — OCI v2 push/pull, lifecycle, scanning, registry, pull-through |
| ECS | 60 | Full API — clusters, task definitions, real task execution, services + rolling deployments, container instances, capacity providers, task sets, ECS Exec |
| Elastic Load Balancing v2 | 51 | ALB/NLB/GWLB CRUD: load balancers, target groups + targets + real health probes, listeners + rules + certificates, LB/listener/target-group attributes, capacity reservations, mTLS trust stores + revocations, SSL policies, resource policies, tags. In-process HTTP data plane for ALBs — per-LB TCP bind, rule matching, forward / fixed-response / redirect, sticky sessions, X-Forwarded-* headers |
| CloudFront | 147 | Distributions + invalidations + tagging + by-X listings + web ACL/alias association. OAC + Cache/OriginRequest/ResponseHeaders/ContinuousDeployment policies. CloudFront Functions, Public Keys, Key Groups, Key Value Stores, OAIs (legacy), Monitoring Subscriptions. Streaming Distributions (legacy RTMP). Field-Level Encryption configs + profiles + Realtime Log Configs. VPC Origins, Anycast IP Lists, Trust Stores, Resource Policies. Connection Groups + Domain Association/DNS Verification + Managed Certificate Details + Promote-Staging Distribution — full CRUD with ETag/If-Match concurrency. REST-XML protocol, full DistributionConfig round-trip incl. origins, cache behaviors, custom error responses, viewer certificates, geo restrictions |
| Route 53 | 71 | Full control plane. Hosted zones + RRsets + health checks + traffic policies + DNSSEC + KSK + query logging + CIDR collections + VPC associations + reusable delegation sets + geo locations + account limits + tags — CRUD, default SOA/NS seeding, INSYNC change tracking, hosted zone limits, list-by-name, TestDNSAnswer. Health checks: full lifecycle, HealthCheckVersion optimistic concurrency, ResetElements, HealthCheckInUse on delete, checker IP ranges. Traffic policies + instances: versioned policies, TrafficPolicyAlreadyExists/InUse, TrafficPolicyInstanceAlreadyExists, list-by-zone/by-policy. DNSSEC + KSK: enable/disable signing, CreateKeySigningKey with KMS-ARN, activate/deactivate, InvalidKeySigningKeyStatus blocks delete-while-active. Query logging: one config per zone, public-zone-only, CloudWatch Logs ARN. CIDR collections: PUT/DELETE_IF_EXISTS atomic changes, CollectionVersion optimistic concurrency, CidrCollectionInUseException on delete-with-locations. VPC associations: associate/disassociate (private-zone only, last-VPC removal blocked), CreateVPCAssociationAuthorization + revoke + list, ListHostedZonesByVPC. Reusable delegation sets: 4-NS synthesis, in-use protection on delete, MAX_ZONES_BY_REUSABLE_DELEGATION_SET limit. Geo locations + account limits + tags: ListGeoLocations/GetGeoLocation over a representative dataset (continents + sample countries + US subdivisions), GetAccountLimit for all 5 owner-scoped types, full tag CRUD on health checks + hosted zones via ChangeTagsForResource/ListTagsForResource/ListTagsForResources. REST-XML under /2013-04-01/ |
| WAF v2 | 55 | Full control plane. WebACLs / RuleGroups / IPSets / RegexPatternSets — Create/Get/List/Update/Delete with LockToken optimistic concurrency (WAFOptimisticLockException on stale tokens, fresh token returned on every mutation). REGIONAL + CLOUDFRONT scope segmentation. ARN-keyed WebACL <-> resource associations (AssociateWebACL/DisassociateWebACL/GetWebACLForResource/ListResourcesForWebACL). WAFAssociatedItemException on delete-while-associated for WebACLs and delete-while-referenced for RuleGroups. CheckCapacity computes WCU as recursive count of statement leaves through AndStatement/OrStatement/NotStatement composition. API keys via CreateAPIKey/DeleteAPIKey/GetDecryptedAPIKey/ListAPIKeys — round-trip the configured TokenDomains. Logging configurations (Put/Get/Delete/List) keyed by WebACL ARN. Permission policies (Put/Get/Delete) on RuleGroups for cross-account share. Tags with WAFNonexistentItemException on unknown ARNs. Managed rule groups + sets: read-only AWS catalog (Common, KnownBadInputs, SQLi), DescribeAllManagedProducts, DescribeManagedProductsByVendor, DescribeManagedRuleGroup, ListAvailableManagedRuleGroups/ListAvailableManagedRuleGroupVersions, GetManagedRuleSet, vendor-side PutManagedRuleSetVersions/UpdateManagedRuleSetVersionExpiryDate. Mobile SDK release lookups + presigned download URL synthesis. GetSampledRequests, GetTopPathStatisticsByTraffic, GetRateBasedStatementManagedKeys return empty observability stubs. JSON 1.1 protocol |
| Application Auto Scaling | 14 | Full control plane. Scalable targets (Register/Deregister/Describe) for ECS, Lambda, DynamoDB, RDS, ElastiCache, SageMaker, EMR, AppStream, Cassandra, Kafka, Neptune, EC2 Spot Fleet, Comprehend. Step + target-tracking + predictive scaling policies (Put/Describe/Delete). Scheduled actions with cron / one-shot start/end times + Timezone. DescribeScalingActivities (IncludeNotScaledActivities), deterministic GetPredictiveScalingForecast with hourly Load + Capacity buckets. RoleARN defaults to the per-namespace service-linked role ARN. Deregister cascades to policies + scheduled actions for that target. TagResource/UntagResource/ListTagsForResource keyed by ARN. JSON 1.1 protocol |
| Athena | 70 | Full control plane. Workgroups (default primary seeded), Data Catalogs (default AwsDataCatalog seeded), Named Queries, Prepared Statements (keyed by (workgroup, statement_name)), Query Executions, Notebooks, Sessions + Calculations, Capacity Reservations + Capacity Assignment Configuration. StartQueryExecution synthesizes a SUCCEEDED execution with a single-row [["1"]] result so callers can immediately fetch via GetQueryResults without polling. DeleteWorkGroup rejects primary and refuses non-empty workgroups unless RecursiveDeleteOption=true. DeleteDataCatalog rejects AwsDataCatalog. Statement classification (DML / DDL / UTILITY) from leading SQL keyword. Tags keyed by ARN across workgroup / datacatalog / capacity-reservation resources. ListEngineVersions / ListApplicationDPUSizes / ListExecutors / GetResourceDashboard return read-only catalog data. JSON 1.1 protocol |
| ACM (Certificate Manager) | 17 | Full control plane. Public-cert lifecycle: RequestCertificate (DNS / EMAIL validation, deterministic synthesized DNS validation records), DescribeCertificate, GetCertificate, ListCertificates, SearchCertificates, DeleteCertificate, RenewCertificate, RevokeCertificate (AMAZON_ISSUED only). Imported certs: ImportCertificate (round-trips PEM, supports re-import to same ARN), ExportCertificate (returns cert + chain + key with passphrase). Tags via Add/Remove/ListTagsForCertificate. Account-wide expiry events via Get/PutAccountConfiguration. UpdateCertificateOptions for transparency-logging + export prefs. ResendValidationEmail only for EMAIL-validated certs. IdempotencyToken dedupes exact matches on token + DomainName + SANs (real ACM keys this on a 1-hour window; fakecloud uses exact match for determinism). JSON 1.1 protocol |
Per-service docs and feature matrices: fakecloud.dev/docs/services.
| What you want to do | Command |
|---|---|
| Test Lambda locally | fakecloud then aws --endpoint-url http://localhost:4566 lambda invoke … |
| Mock DynamoDB in tests | fakecloud then point boto3/aws-sdk at http://localhost:4566 |
| Local S3 for integration tests | fakecloud then use any S3 SDK with endpoint_url=http://localhost:4566 |
| Fake AWS server for tests | fakecloud — single binary on port 4566, any AWS SDK works |
| Replace LocalStack in CI | curl … install.sh, then fakecloud & as a background step |
| Terraform local dev | Point the aws provider endpoints block at http://localhost:4566 |
| CDK local testing | cdklocal deploy --endpoint-url http://localhost:4566 |
| Moto equivalent for Go/Java/Node | fakecloud — real HTTP server, every AWS SDK works, no language lock-in |
| Integration test AWS in GitHub Actions | Install or pull ghcr.io/faiscadev/fakecloud, run as service container |
Full guides: fakecloud.dev/docs/guides.
| Feature | fakecloud | LocalStack Community (post-March 2026) |
|---|---|---|
| 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 |
| Test assertion SDKs | TypeScript, Python, Go, PHP, Java, Rust | Python, Java |
| Cognito User Pools | 122 operations | Paid only |
| SES v2 | Full send + templates + DKIM + suppression | Paid only |
| SES inbound email | Real receipt rule action execution | Stored but never executed |
| RDS | 163 operations, PostgreSQL/MySQL/MariaDB/Oracle/SQL Server/Db2 via Docker, PostgreSQL aws_lambda + aws_s3 extensions, Aurora-compatible MySQL/MariaDB mysql.lambda_async/mysql.lambda_sync |
Paid only |
| ElastiCache | 75 operations, Redis, Valkey, and Memcached via Docker | Paid only |
| API Gateway v1 | 124 operations — REST APIs incl. real Lambda proxy data plane | Paid only |
| API Gateway v2 | 103 operations — HTTP APIs + developer portals | Paid only |
| Bedrock | 111 operations (control plane + runtime) | Not available |
| ECR | 58 operations, real docker push/pull via OCI v2 |
Paid only |
| ECS | 60 operations — full API incl. real task execution, services, task sets, capacity providers | Paid only |
| Elastic Load Balancing v2 | 51 operations ALB/NLB/GWLB incl. mTLS trust stores, capacity reservations, attributes, resource policies, plus an in-process HTTP data plane (rule matching + forward/fixed-response/redirect + sticky sessions) | Paid only |
| CloudFront | 147 operations — distributions, invalidations, tagging, by-X listings, web ACL/alias association. OAC + Cache/OriginRequest/ResponseHeaders/ContinuousDeployment policies. CloudFront Functions, Public Keys, Key Groups, Key Value Stores, Origin Access Identities (legacy), Monitoring Subscriptions. Streaming Distributions (legacy RTMP). Field-Level Encryption configs + profiles + Realtime Log Configs. VPC Origins, Anycast IP Lists, Trust Stores, Resource Policies. Connection Groups + Domain Association/DNS Verification + Managed Certificate Details + Promote-Staging Distribution — full CRUD with ETag/If-Match concurrency. Full DistributionConfig round-trip (origins, cache behaviors, custom error responses, viewer certificates, geo restrictions) |
Paid only |
Performance numbers measured on Apple M1 via
time fakecloud,ps -o rss,ls -lh.
Normal AWS SDKs handle your application code. fakecloud's own SDKs let your tests assert on what happened — sent emails, SNS messages, Lambda invocations, Bedrock calls, and more.
| Language | Install |
|---|---|
| TypeScript | npm install fakecloud |
| Python | pip install fakecloud |
| Go | go get github.com/faiscadev/fakecloud/sdks/go |
| PHP | composer require fakecloud/fakecloud |
| Java | dev.fakecloud:fakecloud (Maven Central) |
| Rust | cargo add fakecloud-sdk |
import { FakeCloud } from "fakecloud";
const fc = new FakeCloud();
// Your app sends through the normal AWS SDK.
// Your test asserts the side effect directly.
const { emails } = await fc.ses.getEmails();
expect(emails).toHaveLength(1);
await fc.reset();Full SDK reference for all six languages: fakecloud.dev/docs/sdks.
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.txt- fakecloud.dev — website
- Getting started — install, first test, SDK setup
- Guides — in-depth how-tos (testing Bedrock, cross-service integration, CI setup)
- Reference — configuration, introspection endpoints, persistence
- Blog — essays and hot takes on testing, AWS, and AI-assisted development
Every published image (fakecloud, fakecloud-postgres, fakecloud-mysql, fakecloud-mariadb) is Trivy-scanned and cosign-signed via GitHub OIDC. Verify before pulling:
cosign verify ghcr.io/faiscadev/fakecloud:latest \
--certificate-identity-regexp '^https://github\.com/faiscadev/fakecloud/' \
--certificate-oidc-issuer https://token.actions.githubusercontent.comSee security docs for details.
Contributions welcome. Fork, branch, write tests, open a PR.
- Conventional commits (
feat:,fix:,chore:,test:,refactor:) - E2E tests for every new action
cargo test --workspace && cargo clippy --workspace -- -D warnings && cargo fmt --check
See CONTRIBUTING.md for more.
fakecloud is free and open-source, licensed under AGPL-3.0-or-later. Using fakecloud as a dev/test dependency has zero AGPL implications for your application — the copyleft clause only applies if you modify and redistribute fakecloud itself as a network service.
Part of the faisca project family | fakecloud.dev