Canonical: fakecloud.dev/blog/migrate-from-localstack
In March 2026, LocalStack replaced its open-source Community Edition with a proprietary image that requires an account and an auth token. If your build broke last month, this guide is for you. If you are still on a pinned older tag and worried about the next pull, this is also for you.
fakecloud is a free, open-source AWS emulator — single binary, no account, no token, no paid tier — that covers the services most teams relied on LocalStack Community for, plus several that moved to LocalStack Pro (RDS, ElastiCache, Cognito User Pools, SES v2, API Gateway v2).
This guide is step-by-step. Copy, paste, done.
The one-line summary
Change the image or the install command. Keep http://localhost:4566 and your dummy credentials. Everything else stays the same.
Step 1: Stop LocalStack
docker compose down
# or: docker kill $(docker ps -q --filter ancestor=localstack/localstack)
Step 2: Install fakecloud
# Option A: single binary, no Docker
curl -fsSL https://raw.githubusercontent.com/faiscadev/fakecloud/main/install.sh | bash
fakecloud
# Option B: Docker
docker run --rm -p 4566:4566 ghcr.io/faiscadev/fakecloud
# Option C: cargo
cargo install fakecloud
fakecloud listens on http://localhost:4566 — same as LocalStack.
Step 3: Keep your SDK wiring
Your application code does not change. Endpoint URL and dummy credentials stay identical:
// TypeScript
import { S3Client } from "@aws-sdk/client-s3";
const s3 = new S3Client({
endpoint: "http://localhost:4566",
region: "us-east-1",
credentials: { accessKeyId: "test", secretAccessKey: "test" },
forcePathStyle: true,
});
# Python (boto3)
import boto3
s3 = boto3.client(
"s3",
endpoint_url="http://localhost:4566",
aws_access_key_id="test",
aws_secret_access_key="test",
region_name="us-east-1",
)
Step 4: Update docker-compose.yml
Before:
services:
localstack:
image: localstack/localstack:latest
ports:
- "4566:4566"
environment:
- SERVICES=s3,sqs,sns,dynamodb,lambda
- DEBUG=1
After:
services:
fakecloud:
image: ghcr.io/faiscadev/fakecloud:latest
ports:
- "4566:4566"
fakecloud starts all services by default (they are lazy and cheap — no SERVICES env var needed).
For Lambda execution you will need Docker-in-Docker or a mounted Docker socket (same as LocalStack Pro required):
services:
fakecloud:
image: ghcr.io/faiscadev/fakecloud:latest
ports:
- "4566:4566"
volumes:
- /var/run/docker.sock:/var/run/docker.sock
Step 5: Update GitHub Actions
Before:
services:
localstack:
image: localstack/localstack
ports:
- 4566:4566
env:
LOCALSTACK_AUTH_TOKEN: ${{ secrets.LOCALSTACK_TOKEN }}
After (install-and-run, no Docker):
steps:
- run: curl -fsSL https://raw.githubusercontent.com/faiscadev/fakecloud/main/install.sh | bash
- run: fakecloud &
- run: |
for i in $(seq 1 30); do
curl -sf http://localhost:4566/_fakecloud/health && exit 0
sleep 1
done
exit 1
~500ms startup vs ~3s for LocalStack container boot. On a cold CI runner the difference adds up over hundreds of test runs.
Step 6: Terraform
Provider block stays the same — only the running emulator changes.
provider "aws" {
access_key = "test"
secret_key = "test"
region = "us-east-1"
skip_credentials_validation = true
skip_metadata_api_check = true
skip_requesting_account_id = true
endpoints {
s3 = "http://localhost:4566"
sqs = "http://localhost:4566"
dynamodb = "http://localhost:4566"
lambda = "http://localhost:4566"
}
}
fakecloud's CI runs the upstream hashicorp/terraform-provider-aws TestAcc* suites against itself, so Terraform flows that worked against LocalStack Community should work against fakecloud.
Things that may need attention
SERVICESenv var. Drop it. fakecloud starts all services by default.
LOCALSTACK_AUTH_TOKEN. Drop it.
Persisted state. LocalStack Pro hasPERSISTENCE=1. fakecloud has--persist /path/to/dir.
Services that moved from LocalStack Community to Pro (and what fakecloud does)
| Service | LocalStack Community now | fakecloud |
|---|---|---|
| Cognito User Pools | Paid only | 122 ops, full auth flows + MFA |
| SES v2 | Paid only | 110 ops, full send + templates + DKIM |
| API Gateway v2 | Paid only | 28 ops, HTTP APIs + JWT/Lambda authorizers |
| RDS | Paid only | 163 ops, real PostgreSQL/MySQL/MariaDB via Docker |
| ElastiCache | Paid only | 75 ops, real Redis/Valkey via Docker |
| Bedrock | Not available | 111 ops (control plane + runtime) |
Test-assertion SDKs (bonus)
fakecloud ships test-assertion SDKs that let you inspect side effects from tests without raw HTTP:
import { FakeCloud } from "fakecloud";
const fc = new FakeCloud();
const { emails } = await fc.ses.getEmails();
expect(emails).toHaveLength(1);
expect(emails[0].destination.toAddresses).toContain("[email protected]");
await fc.reset();
SDKs for TypeScript, Python, Go, PHP, Java, Rust. See the SDK docs.
Verify the migration
aws --endpoint-url http://localhost:4566 s3 mb s3://test-bucket
echo hello | aws --endpoint-url http://localhost:4566 s3 cp - s3://test-bucket/hello.txt
aws --endpoint-url http://localhost:4566 s3 ls s3://test-bucket/
aws --endpoint-url http://localhost:4566 s3 rb s3://test-bucket --force
If it works, migration is done.
Links
- Install:
curl -fsSL https://raw.githubusercontent.com/faiscadev/fakecloud/main/install.sh | bash
- Repo: github.com/faiscadev/fakecloud
- Site: fakecloud.dev
- Issues: github.com/faiscadev/fakecloud/issues