DEV Community

Lucas Vieira
Lucas Vieira

Posted on • Originally published at fakecloud.dev

Migrating from LocalStack to fakecloud in 10 minutes

#aws #testing #localstack #devops

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)
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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,
});
Enter fullscreen mode Exit fullscreen mode 
# 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",
)
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

After:

services:
  fakecloud:
    image: ghcr.io/faiscadev/fakecloud:latest
    ports:
      - "4566:4566"
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

Step 5: Update GitHub Actions

Before:

services:
  localstack:
    image: localstack/localstack
    ports:
      - 4566:4566
    env:
      LOCALSTACK_AUTH_TOKEN: ${{ secrets.LOCALSTACK_TOKEN }}
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

~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"
  }
}
Enter fullscreen mode Exit fullscreen mode

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)

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

await fc.reset();
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

If it works, migration is done.

Links

Top comments (0)