Floci vs LocalStack: emulating AWS locally without account or token, and what to check before migrating

Development
, , , , , ,
1

Floci is a free, MIT-licensed local AWS emulator that serves AWS APIs on localhost:4566 without an account, without a token, and without blocked features. That makes it a direct alternative to LocalStack, which as of March 2026 requires an auth token for its latest image. Whether Floci can replace LocalStack in your pipeline is another question: it depends on which operations your tests call, not on how many service logos the README shows.

Research note: this article is based on Floci’s documentation, release notes, and README, as well as LocalStack’s public announcement. At yoDEV we did not install Floci, run a migration, or reproduce any benchmarks. Versions and plan conditions are current as of September 22, 2026.

What is Floci?

Floci is an open source emulator that runs AWS APIs locally for development, testing, and CI. You point your AWS CLI, SDK, Terraform, CDK, or OpenTofu to http://localhost:4566 and use them as always. At the time of publication, the latest version is 2.1.0, released on September 15, 2026, with Docker images for amd64 and arm64.

Floci offers each service in one of three ways:

  • In-process. Services like S3, SQS, SNS, DynamoDB, IAM, and KMS are emulated by Floci directly.
  • Real backing containers. Lambda, RDS, ElastiCache, MSK, ECS, EKS, and OpenSearch spin up real Docker containers, like Postgres, Valkey, or Redpanda. You get a real database engine, but not the AWS managed service around it.
  • Stubs. Bedrock Runtime, Textract, and Transcribe return fictitious or predefined responses. A service appearing in the AI category doesn’t mean local model inference.

That division matters more than any service count in a headline. The canonical reference is the service matrix, which details the operations supported per service.

Floci or LocalStack?

Choose based on the tests you need to trust, not based on a speed chart. Here’s what the documentation backs:

Floci LocalStack (unified distribution)
Account / auth token Not required Required for latest as of March 2026
License MIT Free plan restricted to non-commercial use
Updates Active versions (2.1.0, September 15, 2026) Updates go to the authenticated image; old Community tags receive no patches
Coverage reference Service matrix by operation LocalStack documentation

Floci’s README also advertises a startup time of around 24 ms and 13 MiB of memory at rest, versus 3.3 s and 143 MiB. These are vendor figures, measured against LocalStack Community’s frozen image and not against LocalStack’s current distribution. They are not a measurement of your workload.

If you’re also evaluating other LocalStack alternatives, we cover MiniStack separately: MiniStack: The Free LocalStack Replacement the Community Was Waiting For.

Is LocalStack still free?

It depends on how you use it. According to LocalStack’s own announcement (published in December 2025 and updated in March 2026), several things changed:

  • Community and Pro were unified into a single image, and running latest requires an auth token.
  • The free plan is intended for non-commercial use.
  • Old Community version tags still run without authentication, but receive no security patches.
  • The Community repository remains public, with reduced maintenance.

Check LocalStack’s current pricing page before deciding. Conditions change, and this article does not cite prices.

What tests to run locally and which in real AWS?

Run locally what is cheap to get wrong and fast to repeat:

  • CRUD against S3, SQS, and DynamoDB
  • Message flow between your own components
  • plan and apply of IaC against disposable resources
  • Test-isolated environments in CI

Keep verifications against real AWS for behavior that an emulator can only approximate:

  • Edge cases in IAM authorization
  • VPC networks, security groups, and cross-account access
  • Timings, retries, and event delivery order
  • Service quotas, throttling, and failure modes of managed services

Your tests passing against Floci proves your code works against Floci. Its compatibility suite (a few thousand automated tests across SDKs and IaC tools) only covers what those tests verify.

Grego’s note: a free emulator is not free infrastructure. Someone on your team owns the pinned version, CI time, and explaining why a test passed locally and failed on AWS. Budget for that before migrating, don’t discover it after.

How to install Floci?

The fastest path in the official documentation is Docker Compose. Pin the version you’re evaluating instead of using latest:

services:
  floci:
    image: floci/floci:2.1.0
    ports:
      - "4566:4566"

docker compose up -d

Then point your AWS tools to Floci with dummy credentials:

export AWS_ENDPOINT_URL=http://localhost:4566
export AWS_DEFAULT_REGION=us-east-1
export AWS_ACCESS_KEY_ID=test
export AWS_SECRET_ACCESS_KEY=test

The documentation suggests adding these variables to your shell profile. We recommend limiting them to your test environment, so a stray command never reaches a real endpoint with wrong assumptions.

Quick test, taken from the quick start:

aws s3 mb s3://my-bucket --endpoint-url $AWS_ENDPOINT_URL
aws s3 ls --endpoint-url $AWS_ENDPOINT_URL

How to Use Floci with Testcontainers?

To isolate each test, Floci publishes Testcontainers modules:

  • Java: io.floci:testcontainers-floci
  • Node.js: @floci/testcontainers
  • Python: testcontainers-floci
  • .NET: Testcontainers.Floci
  • Go: was listed as in development at the time of publishing this note.

Each module spins up a fresh Floci container per test and exposes its endpoint and credentials. In Python:

pip install testcontainers-floci

import boto3
from floci import FlociContainer

def test_s3_create_bucket():
    with FlociContainer() as floci:
        s3 = boto3.client(
            "s3",
            endpoint_url=floci.get_endpoint(),
            region_name=floci.get_region(),
            aws_access_key_id=floci.get_access_key(),
            aws_secret_access_key=floci.get_secret_key(),
        )
        s3.create_bucket(Bucket="my-bucket")

How to Migrate from LocalStack to Floci?

The migration guide describes most cases as a simple image swap. Review each of these points against your own configuration:

  1. Image. Replace localstack/localstack with floci/floci:2.1.0. If your startup scripts call aws or boto3, use floci/floci:2.1.0-compat, which includes the AWS CLI and boto3.
  2. Environment variables. Floci automatically translates LocalStack variables like LOCALSTACK_HOST, PERSISTENCE, and LAMBDA_DOCKER_NETWORK. Set LOCALSTACK_PARITY=false to disable that translation.
  3. Startup scripts. Scripts in /etc/localstack/init/ run without changes.
  4. State directory. LocalStack stores data in /var/lib/localstack; Floci uses /app/data, so update your volumes accordingly.
  5. Health checks. /_localstack/health and /_localstack/init remain available. The log also ends with a Ready. line in LocalStack style, so the default wait strategy from LocalStackContainer in Testcontainers continues to work.
  6. Known differences. LAMBDA_REMOTE_DOCKER is not supported, selection with SERVICES is ignored (all services start), and Lambda always runs in Docker.
  7. Behavior, not just startup. Run your suite again. Pay attention to endpoint resolution, persistence across restarts, and error paths, not just the happy path.

Is It Safe to Mount the Docker Socket?

It’s powerful access to the host, and it should be treated that way. Services backed by real containers (Lambda, RDS, ElastiCache, and others) need to mount /var/run/docker.sock inside Floci. Any process with access to that socket can control Docker on the host. Some practical rules:

  • Mount it only if you need container-backed services.
  • Keep the listener local.
  • Use disposable data and dummy credentials.
  • Don’t expose this configuration to untrusted CI workloads.

The Floci container runs by default with an unprivileged user. According to Docker configuration documentation, FLOCI_RUN_AS_ROOT=true is only for hosts where the socket is accessible only to root.

Should You Migrate to Floci?

Floci eliminates the friction of account and token management in local AWS tests, and its release cadence is active. Still, the decision comes down to an inventory: list the exact operations your application calls, compare them against the service matrix, and run your own suite against a pinned version before switching your CI.