Hector Ventura

Posted on Apr 29

Meet Floci: a fast, free, no-strings AWS emulator (no auth token, no quotas)

#testing #devops #opensource #aws

If you write code against AWS, you've probably hit one of these in the last year:

LocalStack Community Edition sunset in March 2026. Auth tokens, frozen security updates, paid tiers for the things that used to be free.
Spinning up real AWS for local dev or CI is slow, expensive, and risky.
Mock libraries lie to you until production day.

I started Floci to fix this. It's a single Docker image, MIT-licensed, no account, no telemetry, no feature gates. Pull and go.

TL;DR: docker run -p 4566:4566 floci/floci:latest and you have 40+ AWS services on http://localhost:4566. Same port and SDK calls as LocalStack. Switch by changing one env var.

🔗 GitHub: github.com/floci-io/floci
🔗 Docs: floci.io/floci

Why I built it

I was tired of three things:

Hidden costs. Free emulators that "encourage" you toward a paid tier the moment your team grows past 1.
Slow startup. Booting an emulator that takes 3+ seconds for every CI job multiplies into hours of waste per week.
Mock-only fidelity. Some services (Lambda, RDS, ElastiCache, Athena, EKS) need a real engine, not a JSON shim that pretends.

Floci is what I wished existed.

What makes Floci different

1. It's actually fast

Floci is built on Quarkus + GraalVM native image. No JVM warmup, no Python interpreter startup.

	Floci	LocalStack
Cold start	~24 ms	~3,300 ms
Idle memory	~13 MiB	~143 MiB
Image size	~90 MB	~2 GB

That gap is why Floci is comfortable on your smallest CI runner. A test that spins up a fresh emulator per job suddenly stops being painful.

2. Real Docker where it matters

Mock-only emulators are fine until your code starts depending on the real engine's behavior. Floci spins up real Docker containers for the services where wire protocols and execution semantics matter:

Lambda: real container per function, warm pool, aliases, Function URLs, SQS/Kinesis/DDB Streams event source mappings
RDS: actual PostgreSQL and MySQL containers with JDBC wire protocol proxying
ElastiCache: real Redis/Valkey with RESP proxying and IAM/SigV4 token validation
MSK: real Apache Kafka clusters
OpenSearch / EKS / ECS: real engines and orchestrators where applicable

This is the architecture from day one, not a feature flag, not a paid add-on.

3. Genuinely free and open

MIT licensed. Fork it, embed it, ship it inside your product. No "community edition sunset" coming.
No auth token. Ever.
No telemetry. Floci doesn't phone home.
No CI quota. Run 100,000 jobs a day if you want.
No feature gates. Every supported service is available to everyone.

4. Wire-compatible with the real AWS SDKs

Floci is validated by 1,850+ automated compatibility tests running across:

AWS SDK for Java v2
AWS SDK for JavaScript v3
boto3 (Python)
AWS CLI v2
AWS SDK for Go v2
AWS SDK for Rust
Terraform / OpenTofu / AWS CDK

The principle: the SDK source is the contract. If the official SDK can't tell Floci apart from AWS at the wire level, the test passes. If it can, that's a bug.

5. Drop-in for LocalStack users

Same default port (4566). Same wire protocols. Same SDK endpoint override. Migration is one env var:

- AWS_ENDPOINT_URL=http://localstack:4566
+ AWS_ENDPOINT_URL=http://floci:4566

That's it. Your application code, your IaC, your tests, all unchanged.

The 30-second tour

# docker-compose.yml
services:
  floci:
    image: floci/floci:latest
    ports:
      - "4566:4566"
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
      - ./data:/app/data

docker compose up -d

# Overwrite the aws-cli default URL endpoint
export AWS_ENDPOINT_URL="http://localhost:4566"

aws s3 mb s3://my-bucket
aws sqs create-queue --queue-name my-queue
aws dynamodb list-tables

In Java with the AWS SDK v2:

S3Client s3 = S3Client.builder()
    .endpointOverride(URI.create("http://localhost:4566"))
    .region(Region.US_EAST_1)
    .credentialsProvider(StaticCredentialsProvider.create(
        AwsBasicCredentials.create("test", "test")))
    .forcePathStyle(true)
    .build();

Done.

Testcontainers integration (it just works)
If you write JUnit/Spring Boot tests, there's an official Testcontainers module on Maven Central. No manual GenericContainer setup, no port juggling.

<dependency>
    <groupId>io.floci</groupId>
    <artifactId>testcontainers-floci</artifactId>
    <version>2.1.0</version>
    <scope>test</scope>
</dependency>

Then in your test:

@Testcontainers
class S3IntegrationTest {

    @Container
    static FlociContainer floci = new FlociContainer();

    @Test
    void shouldCreateBucket() {
        S3Client s3 = S3Client.builder()
            .endpointOverride(URI.create(floci.getEndpoint()))
            .region(Region.of(floci.getRegion()))
            .credentialsProvider(StaticCredentialsProvider.create(
                AwsBasicCredentials.create(floci.getAccessKey(), floci.getSecretKey())))
            .forcePathStyle(true)
            .build();

        s3.createBucket(b -> b.bucket("my-bucket"));
    }
}

There's also spring-boot-testcontainers-floci for Spring Boot users. auto-configures Spring Cloud AWS to point at the container, zero boilerplate.
Module page: testcontainers.com/modules/floci

What's supported today

40+ services and growing. The big ones: S3, SQS, SNS, DynamoDB (+ Streams), Lambda, API Gateway v1 & v2, Cognito, KMS, Secrets Manager, IAM, STS, Step Functions, CloudFormation, EventBridge (+ Scheduler), CloudWatch Logs/Metrics, Kinesis, ElastiCache (Redis/Valkey), RDS (PostgreSQL/MySQL), ECS, EC2, OpenSearch, EKS, MSK, Glue, Athena, Data Firehose, ACM, AppConfig, Bedrock Runtime, SES/SES v2, SSM Parameter Store, etc.

Full per-service operation list: floci.io/floci/services

Where it's heading

EC2 with real Docker-backed compute (alpha)
Quarkus DevServices integration for Java devs
A per-language, per-service compatibility status dashboard

If any of that interests you or if a service you need isn't there yet, I'd love your input. Floci already has a great roster of contributors fixing real bugs and adding real services. There's room for more.

How to help

If Floci sounds useful:

⭐ Star the repo: github.com/floci-io/floci. It genuinely helps surface the project to other devs in the same boat
💬 Join Slack: community workspace at floci.slack.com. Questions, feedback, and weird edge cases all welcome
🐛 Open an issue: found a wire-level mismatch with the real AWS SDK? That's exactly the kind of bug I want to know about
🤝 Contribute: good first issues are labeled, and PRs that add a missing API operation are very welcome

Thanks for reading and if you give Floci a try, let me know what works and what doesn't. The whole point is to be the emulator developers actually want to use.

DEV Community