# fakecloud

> fakecloud is a free, open-source local AWS cloud emulator written in Rust. It runs on a single port (4566), requires no account or auth token, and aims for 100% behavioral parity with real AWS across every service, every operation, and every cross-service integration. It is an open-source alternative to LocalStack, which went proprietary in March 2026.

- **Goal:** 100% of AWS services, each at 100% conformance, with 100% of cross-service integrations. Approach is depth-first — a service is added when it passes the full Smithy-model test variants and cross-service wire-ups, not when the API surface looks filled in.
- Single static binary (~19 MB), ~300ms startup, ~10 MiB idle memory, no Docker required to run fakecloud itself
- **105 AWS services shipped today, 7,391 operations, true 100% Smithy conformance — 248,319/248,319 generated test variants pass on every commit**, no flake margin and no skipped services. More services land as they hit the conformance bar; roadmap is driven by real-project demand.
- Services: S3, SQS, SNS, EventBridge, EventBridge Pipes, EventBridge Scheduler, Lambda, EC2, DynamoDB, IAM, STS, Organizations, SSM, Secrets Manager, CloudWatch Logs, CloudWatch (Metrics & Alarms), KMS, CloudFormation, Cloud Control API, SES (v2 + v1 inbound), Cognito User Pools, Cognito Identity, Kinesis, Firehose, RDS, RDS Data API, Aurora DSQL, Resource Groups, Resource Groups Tagging API, ElastiCache, MemoryDB, EKS, AWS Backup, AWS AppConfig, Cloud Map, Step Functions, API Gateway v1 (REST), API Gateway v2 (HTTP), Bedrock, Bedrock Agent, Bedrock Agent Runtime, Bedrock Runtime, ECR, ECS, Elastic Load Balancing v2, CloudFront, CloudTrail, Route 53, WAF v2, Application Auto Scaling, Athena, ACM, Glue
- 30+ cross-service integrations: S3 notifications, SNS fan-out, EventBridge rules, DynamoDB Streams, CloudWatch Logs subscriptions, Cognito triggers, API Gateway -> Lambda, Step Functions task integrations, SES inbound -> S3/SNS/Lambda, and more
- Real Lambda execution via Docker across 23 runtimes (Node.js 16/18/20/22/24, Python 3.8/3.9/3.10/3.11/3.12/3.13/3.14, Java 11/17/21/25, Go 1.x, Ruby 3.3/3.4, .NET 8/10, custom `provided.al2` / `provided.al2023`)
- Real stateful services: RDS runs real PostgreSQL/MySQL/MariaDB/Oracle/SQL Server/Db2 via Docker; ElastiCache runs real Redis/Valkey/Memcached via Docker
- First-party test-assertion SDKs for TypeScript, Python, Go, PHP, Java, and Rust — assert on emails sent, SNS messages published, Lambda invocations, Cognito confirmation codes, etc. without raw HTTP
- Multi-account, SCPs, ABAC (tag-based conditions), permission boundaries, session policies, KMS key policies, bucket policies — full Allow/Deny/NotPrincipal semantics
- CI runs upstream `hashicorp/terraform-provider-aws` `TestAcc*` suites against fakecloud to catch provider-level drift
- AGPL-3.0 licensed, free for commercial use, no account or auth token required

## Install

- [Install script](https://fakecloud.dev/install.sh): `curl -fsSL https://fakecloud.dev/install.sh | bash` (macOS + Linux)
- [Homebrew](https://formulae.brew.sh/formula/fakecloud): `brew install fakecloud`
- [Cargo install](https://crates.io/crates/fakecloud): `cargo install fakecloud`
- [Docker](https://github.com/faiscadev/fakecloud/pkgs/container/fakecloud): `docker run --rm -p 4566:4566 ghcr.io/faiscadev/fakecloud`

## Usage

- [Quick start](https://fakecloud.dev#quickstart): Run `fakecloud` then point any AWS SDK at `http://localhost:4566` with dummy credentials (access_key=test, secret_key=test)
- [Configuration](https://github.com/faiscadev/fakecloud#configuration): CLI flags and environment variables (`--addr`, `--region`, `--account-id`, `--log-level`, `--persist`, `--verify-sigv4`, `--iam soft|strict`)
- [Health check](https://fakecloud.dev/docs/reference): `curl http://localhost:4566/_fakecloud/health`
- [LocalStack migration guide](https://fakecloud.dev/blog/migrate-from-localstack/): step-by-step migration from LocalStack Community with copy-paste configs for docker-compose, GitHub Actions, Terraform, CDK, Serverless Framework
- [Integration testing AWS in CI](https://fakecloud.dev/blog/integration-testing-aws-in-ci/): GitHub Actions, GitLab CI, CircleCI workflow examples
- [Test Lambda locally](https://fakecloud.dev/blog/test-lambda-locally/): full Lambda tutorial with SQS/S3/EventBridge triggers
- [Moto equivalent for Go/Java/Node](https://fakecloud.dev/blog/moto-equivalent-go-java-node/): using fakecloud from non-Python languages

## Supported Services

- **S3** (107 ops): buckets, objects, multipart uploads, versioning, lifecycle, CORS, notifications, object lock, replication, website hosting
- **SQS** (23 ops): queues, messages, long polling, FIFO, dead-letter queues, batch operations
- **SNS** (42 ops): topics, subscriptions, publishing, filter policies, SQS/Lambda/HTTP fan-out
- **EventBridge** (57 ops): event buses, rules, targets, archives, replays, connections, API destinations, pattern matching
- **EventBridge Scheduler** (12 ops): at/rate/cron schedules, SQS targets, DLQ routing, one-shot self-delete
- **Lambda** (70 ops): function CRUD, real code execution via Docker across 23 runtimes, event source mappings (SQS, Kinesis, DynamoDB Streams), layers, versions, aliases, URL endpoints
- **DynamoDB** (57 ops): tables, items, transactions, PartiQL, backups, global tables, streams
- **IAM** (176 ops): users, roles, groups, policies, instance profiles, OIDC/SAML providers, MFA, permission boundaries, session policies, ABAC tag conditions
- **STS** (11 ops): AssumeRole, AssumeRoleWithWebIdentity, GetSessionToken, GetCallerIdentity, session tags, external IDs, federation
- **SSM** (152 ops): Parameter Store (hierarchical parameters with KMS), documents, commands, maintenance windows, patch baselines
- **Secrets Manager** (23 ops): secret CRUD, versioning, rotation via Lambda, replication, soft delete/restore
- **CloudWatch Logs** (118 ops): log groups, streams, events, filtering, subscription filters, query language, metric filters, retention
- **KMS** (53 ops): symmetric/asymmetric keys, encrypt/decrypt, aliases, grants, data keys, real ECDH, key import, multi-region keys
- **CloudFormation** (90 ops): stacks, resource provisioning, template parsing, intrinsic functions, custom resources, drift detection, change sets
- **Cloud Control API** (8 ops): uniform create/read/update/delete/list over CloudFormation resource types, real provisioners (container-backed included), RFC 6902 JSON Patch updates, ClientToken idempotency, request tracking
- **Resource Groups** (23 ops): groups defined by tag/CloudFormation-stack resource queries, explicit membership (GroupResources/UngroupResources/ListGroupResources), group configuration, tagging, account settings, grouping statuses, tag-sync tasks; account-partitioned and persisted
- **SES** (112 ops): v2 API (send email, templates, configuration sets, event destinations, DKIM, suppression list) + v1 inbound (receipt rules with real S3/SNS/Lambda action execution, receipt filters)
- **Cognito User Pools** (129 ops): user pools, app clients, users, groups, MFA (SMS, TOTP, WebAuthn), identity providers (Google, Facebook, SAML, OIDC), resource servers, domains, devices, full authentication flows (USER_PASSWORD_AUTH, USER_SRP_AUTH, REFRESH_TOKEN_AUTH, CUSTOM_AUTH), triggers
- **Kinesis** (39 ops): data streams, records, shard iterators, retention changes, enhanced fan-out consumers, tagging
- **RDS** (163 ops): DB instances with real PostgreSQL/MySQL/MariaDB/Oracle/SQL Server/Db2 engines via Docker, snapshots, read replicas, parameter groups, subnet groups, engine/version discovery, tagging
- **ElastiCache** (75 ops): cache clusters with real Redis/Valkey/Memcached via Docker, replication groups, global replication groups, serverless caches and snapshots, subnet groups, users/user groups, failover, tagging
- **MemoryDB** (45 ops): full control plane for Redis/Valkey clusters, shards, ACLs, users, parameter/subnet groups, snapshots, multi-region clusters, reserved nodes; persisted. Data-plane container backing is a follow-up
- **EKS** (65 ops, complete): full Elastic Kubernetes Service control plane — clusters (incl. connected register/deregister), managed node groups, Fargate profiles, add-ons, access entries + access policies, OIDC identity-provider configs, pod-identity associations, upgrade insights, capabilities, encryption config, EKS Anywhere subscriptions (create/describe/list/delete, config + version updates with tracking, cluster-version/add-on/access-policy catalogues, tagging); persisted, `CREATING` -> `ACTIVE` on describe. No real Kubernetes control-plane endpoint
- **AWS Backup** (109 ops, complete): full AWS Backup control plane — backup plans (+ versions) + selections, vaults (standard / logically-air-gapped / restore-access) with notifications / access policies / lock config, recovery points, backup / copy / restore / scan jobs (progressed synthetically to a terminal state; `StartBackupJob` records a synthetic recovery point that `DescribeRecoveryPoint` resolves), frameworks, report plans + jobs, legal holds, restore-testing plans + selections, tiering configurations, protected resources, tags, global / region settings; persisted. No real backup engine (control-plane emulation, matching LocalStack Community)
- **Cloud Map** (30 ops, complete): full AWS Cloud Map (`servicediscovery`) control plane + discovery — HTTP/public-DNS/private-DNS namespaces, services (DnsConfig/HealthCheck + attributes), instance register/deregister/get/list + health status, `DiscoverInstances`/`DiscoverInstancesRevision` lookup, tagging; via the async operation model (mutations return an `OperationId` that settles `SUCCESS` on `GetOperation`); persisted
- **Step Functions** (37 ops): state machines, executions, full ASL interpreter (Pass, Task, Choice, Wait, Parallel, Map, Succeed, Fail), Retry/Catch, Lambda/SQS/SNS/EventBridge/DynamoDB task integrations
- **API Gateway v1** (124 ops): REST APIs, resources, methods, integrations (`MOCK`/`HTTP`/`HTTP_PROXY`/`AWS_PROXY` Lambda v1.0 proxy event), method/integration responses, deployments, stages with cache flush, models, request validators, authorizers (TOKEN/REQUEST/COGNITO), API keys + usage plans + usage plan keys, VPC links, domain names + base path mappings, client certificates, documentation parts/versions, gateway responses, exports/SDKs, tagging, account
- **API Gateway v2** (103 ops): HTTP APIs, routes with path parameters and wildcards, Lambda proxy integration v2.0, HTTP proxy, mock integrations, stages, deployments, JWT and Lambda authorizers, domain names, API mappings, models, route responses, integration responses, routing rules, VPC links, CORS, developer portals + portal products + product pages, tags
- **Bedrock** (101 ops): foundation models, guardrails, custom models, import/copy/invocation/evaluation jobs, inference profiles, prompt routers, marketplace endpoints, automated reasoning policies
- **Bedrock Runtime** (10 ops): InvokeModel (Anthropic, Titan, Meta, Cohere, Mistral), Converse, streaming, ApplyGuardrail, CountTokens, async invoke, configurable responses, fault injection
- **ECR** (58 ops): full registry — repos, images (real OCI v2 push/pull via `docker push`/`pull`), lifecycle policies, scanning, pull-through cache, registry settings, signing
- **ECS** (77 ops): clusters, task definitions, real Fargate-style task execution via Docker, services with rolling deployments, container instances, capacity providers, task sets, ECS Exec
- **Elastic Load Balancing v2** (51 ops, Application/Network/Gateway): load balancer CRUD, target groups + targets + real health probes, listeners + rules + certificates, LB/listener/target-group attributes, capacity reservations, mTLS trust stores + revocations, subnets, security groups, IP address types, IPAM pools, 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 ops): distributions, invalidations, 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 `DistributionConfig` round-trip with ETag/If-Match concurrency
- **Route 53** (71 ops): hosted zones + RRsets + health checks + traffic policies + DNSSEC + KSK + query logging + CIDR collections + VPC associations + reusable delegation sets + geo locations + account limits + tags. Default SOA/NS seeding, `INSYNC` change tracking, `HealthCheckVersion` optimistic concurrency, `CollectionVersion` optimistic concurrency on CIDR changes, `TestDNSAnswer` synthesis. REST-XML under `/2013-04-01/`
- **ACM (Certificate Manager)** (17 ops): public-cert lifecycle (`RequestCertificate` with DNS / EMAIL validation, deterministic synthesized DNS validation records), `Describe`/`Get`/`List`/`Search`/`Delete`/`Renew`/`Revoke`. Imported certs (`ImportCertificate` round-trips PEM + supports re-import to same ARN, `ExportCertificate` returns cert + chain + key with passphrase). `IdempotencyToken` dedupe matching real ACM's 1-hour window. `ResendValidationEmail` only for EMAIL-validated certs
- **Application Auto Scaling** (14 ops): 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, scheduled actions with cron / one-shot start/end times + Timezone. Deterministic `GetPredictiveScalingForecast` with hourly Load + Capacity buckets capped at one week. `Deregister` cascades to policies + scheduled actions
- **WAF v2** (55 ops): WebACLs / RuleGroups / IPSets / RegexPatternSets with `LockToken` optimistic concurrency that rotates on every successful mutation. REGIONAL + CLOUDFRONT scope segmentation. Web ACL <-> resource associations, `WAFAssociatedItemException` blocks delete-while-associated. `CheckCapacity` computes WCU as recursive count of statement leaves through `AndStatement`/`OrStatement`/`NotStatement`. API keys, logging configs, permission policies, managed rule catalog (Common, KnownBadInputs, SQLi), mobile SDK release lookups + presigned URL synthesis. Control-plane only — no actual HTTP request inspection
- **Athena** (70 ops): 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, tags. `StartQueryExecution` synthesizes a SUCCEEDED execution with a one-row `[["1"]]` result so callers can immediately fetch via `GetQueryResults` without polling. `DeleteWorkGroup` rejects `primary`. Not a SQL engine — every query returns the synthesized result
- **Cognito Identity** (23 ops): identity pools, federated identities, `GetId`/`GetCredentialsForIdentity`/`GetOpenIdToken`, developer-authenticated identities, identity pool roles + role mappings, tagging
- **CloudWatch (Metrics & Alarms)** (49 ops): metrics (`PutMetricData`/`GetMetricData`/`GetMetricStatistics`/`ListMetrics`/`GetMetricWidgetImage`), metric + composite alarms with SNS/AppAS/EC2 actions on threshold transitions, dashboards, anomaly detectors, insight rules, metric streams, alarm mute rules, contributor insights, tagging. awsQuery protocol (SigV4 service `monitoring`)
- **AWS AppConfig** (58 ops, complete): one crate serving both `appconfig` (56 ops) and `appconfigdata` (2 ops) — applications, environments, configuration profiles, hosted configuration versions (raw bytes + content type stored/returned verbatim, auto-incrementing version), custom + AWS-predefined deployment strategies, deployments (settle to `COMPLETE`), extensions + associations, experiments, account settings, `ValidateConfiguration`, tags; persisted. Real data plane: `StartConfigurationSession` -> `GetLatestConfiguration` serves the deployed hosted-config bytes
- **CloudTrail** (60 ops, awsJson1.1): control plane for trails (`CreateTrail`/`GetTrail`/`UpdateTrail`/`DeleteTrail`/`DescribeTrails`/`ListTrails`), per-trail logging that `GetTrailStatus` reflects (`StartLogging`/`StopLogging` toggle `IsLogging`, which starts `false`), event + insight selectors that persist and round-trip, CloudTrail Lake event data stores (full CRUD + `RestoreEventDataStore` + ingestion/federation toggles), channels, imports, Lake queries (settle to `FINISHED` with empty rows), dashboards, resource policies, organization delegated admins, event configuration, and tagging. `LookupEvents`/`ListPublicKeys`/`ListInsightsMetricData` return real empty result sets. Account-partitioned and persisted. Control-plane only — no event-recording engine, matching how LocalStack Community mocks CloudTrail
- **Firehose** (12 ops): delivery streams with real S3 destination delivery, `ExtendedS3`/`Redshift`/`OpenSearch`/`Splunk`/`HttpEndpoint`/`Snowflake`/`Iceberg` destination round-trip, `BufferingHints` range checks, server-side encryption, `PutRecord`/`PutRecordBatch` with per-record IDs, tagging
- **Glue** (269 ops): Data Catalog (databases, tables, partitions with `GetPartitions` expression pruning), jobs, crawlers, classifiers, connections, triggers, workflows, blueprints, dev endpoints, schema registry, interactive sessions, ML transforms, data quality, UDFs, column statistics, tagging. Real status lifecycles; job/Spark execution synthesized
- **Organizations** (63 ops): org tree (roots/OUs/accounts), `CreateAccount` async `IN_PROGRESS -> SUCCEEDED`, policies (SCP/TAG/BACKUP/AISERVICES_OPT_OUT) with **real SCP enforcement** as a permission ceiling under `FAKECLOUD_IAM=strict`, handshakes, delegated administrators, AWS service access, billing responsibility transfers, resource policy, tagging
- **Bedrock Agent** (72 ops): agents, agent versions/aliases, action groups, knowledge bases, data sources, flows, prompts, agent collaborators, tagging
- **Bedrock Agent Runtime** (31 ops): `InvokeAgent`, `InvokeFlow`, `Retrieve`, `RetrieveAndGenerate`, session management, memory, with configurable + streaming responses
- **EC2** (775 ops): the complete EC2 control plane — VPCs, subnets, security groups, route tables, gateways, instances, EBS, AMIs, the full 74-op Transit Gateway surface, Site-to-Site + Client VPN, IPAM, Verified Access, Network Insights, and Outpost / local-gateway networking. Instances run as real containers — Docker/Podman by default or native Kubernetes Pods (`FAKECLOUD_EC2_BACKEND=k8s`) — running user-data at boot, with start/stop/reboot/terminate mapped to the container lifecycle and `GetConsoleOutput` returning the container log; degrades to metadata-only when no container runtime is present. Real network isolation: a default VPC ships per account+region; each subnet gets its own daemon bridge (cross-VPC instances can't route to each other), and security-group/NACL rules are enforced via host nftables (opt-in `FAKECLOUD_EC2_SG_ENFORCEMENT`, needs CAP_NET_ADMIN) on Docker/Podman or via NetworkPolicy on Kubernetes, degrading to tracked-only without the capability. `ec2Query` protocol with flattened-XML lists

## Introspection endpoints (for tests)

fakecloud exposes `/_fakecloud/*` endpoints your tests can use to assert on side effects and reset state between tests. Wrapped by first-party SDKs in TypeScript, Python, Go, PHP, Java, Rust.

- `GET /_fakecloud/health`: liveness check
- `POST /_fakecloud/reset`: wipe all state (use between tests)
- `GET /_fakecloud/ses/emails`: list emails that were sent
- `GET /_fakecloud/sns/messages`: list SNS messages that were published
- `GET /_fakecloud/lambda/invocations`: list Lambda invocations and their results
- `GET /_fakecloud/cognito/confirmation-codes`: list Cognito confirmation codes (for testing signup flows)
- `POST /_fakecloud/iam/create-admin`: bootstrap an admin user in a specific account (for multi-account tests)
- `GET /_fakecloud/credentials`: vends AWS container-credentials-format JSON; point `AWS_CONTAINER_CREDENTIALS_FULL_URI` here to run an app that expects an instance/task role unmodified (no static keys)
- EC2 IMDS on `/latest/*` (IMDSv1 + IMDSv2): point `AWS_EC2_METADATA_SERVICE_ENDPOINT=http://localhost:4566/` to resolve credentials + instance identity via the metadata service unmodified. `--imds-link-local` (root) also binds the real `169.254.169.254`/`169.254.170.2` IPs for apps that hardcode them
- `--dns` runs a real DNS resolver (UDP+TCP) answering A/AAAA/CNAME/MX/TXT from the Route 53 records you create, so `dig`/`getaddrinfo` and containers pointed at fakecloud resolve created records to local targets (one source of truth, no dnsmasq/hosts layer). CNAME chase; names in no local zone forward upstream so fakecloud can be a container's sole resolver. `GET /_fakecloud/dns/resolve?name=&type=` (wrapped as `dns_resolve`/`dnsResolve` in every SDK) returns the same resolution as JSON so a test can assert it without a socket
- `GET /_fakecloud/elbv2/load-balancers`: list ALB/NLB/GWLB load balancers (for testing infra setups)
- `GET /_fakecloud/elbv2/target-groups`: list target groups
- `GET /_fakecloud/elbv2/listeners`: list listeners
- `GET /_fakecloud/elbv2/rules`: list listener rules
- `GET /_fakecloud/ec2/instances`: list EC2 instances with control-plane metadata (id, state, type, AMI, IPs, AZ)
- `GET /_fakecloud/ec2/instance-networks`: inspect each instance's backing network (Docker/Podman network or k8s NetworkPolicy), container IP, isolation backend, and whether security-group enforcement is active
- See [SDK docs](https://fakecloud.dev/docs/sdks/) for the full endpoint list

## Optional

- [Source code](https://github.com/faiscadev/fakecloud): GitHub repository
- [Issues](https://github.com/faiscadev/fakecloud/issues): bug reports and feature requests — fakecloud's roadmap is demand-driven
- [Architecture](https://github.com/faiscadev/fakecloud#architecture): Cargo workspace structure and protocol details
- [Contributing](https://github.com/faiscadev/fakecloud/blob/main/CONTRIBUTING.md): contribution guidelines
- [LocalStack alternative page](https://fakecloud.dev/localstack-alternative/): detailed feature comparison with LocalStack Community (post-March 2026)
- [Four-way comparison](https://fakecloud.dev/blog/localstack-alternatives-compared/): fakecloud vs MiniStack vs floci vs Moto vs LocalStack Pro