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

• SERVICES env var. Drop it. fakecloud starts all services by default.
• LOCALSTACK_AUTH_TOKEN. Drop it.
• Persisted state. LocalStack Pro has PERSISTENCE=1. fakecloud has --persist /path/to/dir.

Services that moved from LocalStack Community to Pro (and what fakecloud does)

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("alice@example.com");

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