Introducing Floci: The Fast, Free, and Open-Source AWS Emulator

Local development against AWS services has always been painful. You either run real AWS (expensive, slow, requires an internet connection) or use an emulator. For years, LocalStack was the go-to choice — until they required auth tokens and locked down their community edition in early 2026.

That gap is exactly what Floci fills.

Key Numbers: Native Floci vs LocalStack

What Is Floci?

Floci is a free, open-source local AWS service emulator written in Java using Quarkus and compiled to a native binary via GraalVM Mandrel. It runs as a single process on port 4566 — the same port LocalStack uses — so switching requires zero changes to your existing code or tooling.

The name comes from cirrocumulus floccus (abbreviated floci), a cloud formation that looks like popcorn — small, fluffy, and lightweight. That ethos drives the entire design: minimal footprint, fast startup, and no unnecessary overhead.

Startup time:  24 ms  (native) / 684 ms (JVM)
Idle memory:   13 MiB (native) / 78 MiB (JVM)
License:       MIT
Auth required: Never

Architecture Overview

Floci follows a clean three-layer architecture for every AWS service it emulates:

flowchart LR
    Client["☁️ AWS SDK / CLI"]

    subgraph Floci ["Floci — port 4566"]
        Router["HTTP Router"]

        subgraph Stateless ["Stateless Services"]
            A["SSM · SQS · SNS
IAM · STS"]
        end

        subgraph Persistent ["Stateful Services"]
            B["S3 · DynamoDB
API Gateway"]
        end

        subgraph Container ["Container Services"]
            C["Lambda · ElastiCache · RDS"]
        end

        Router --> A
        Router --> B
        Router --> C
        A & B --> Store[("Storage
(memory / disk)")]
    end

    Docker["🐳 Docker"]

    Client -->|"HTTP :4566"| Router
    C -->|"Docker API"| Docker

Request Flow

Every AWS request goes through the same pipeline:

sequenceDiagram
    participant SDK as AWS SDK
    participant C as Controller
    participant S as Service
    participant B as StorageBackend

    SDK->>C: HTTP POST (AWS wire protocol)
    C->>C: Parse X-Amz-Target / URL path
    C->>S: Call service method
    S->>B: put / get / delete / scan
    B-->>S: Result
    S-->>C: Domain object
    C-->>SDK: AWS-format XML / JSON response

Supported AWS Services

Floci covers 22 AWS service families out of the box:

Storage Architecture

One of Floci’s most flexible design decisions is its pluggable storage layer. Every service gets its own backend, and backends are configurable per service.

flowchart LR
    subgraph Services
        SSM2["SSM Service"]
        SQS2["SQS Service"]
        S32["S3 Service"]
    end

    subgraph SB ["StorageBackend interface"]
        direction TB
        IM["InMemoryStorage
ConcurrentHashMap
Ephemeral, fastest"]
        PS["PersistentStorage
JSON files, atomic writes
Survives restarts"]
        HS["HybridStorage ✓ default
In-memory reads
Async disk flush"]
        WS["WalStorage
Write-ahead log
High-throughput workloads"]
    end

    SSM2 --> HS
    SQS2 --> IM
    S32 --> HS
    HS --> Disk[("./data/*.json")]
    PS --> Disk
    WS --> Disk

The default HybridStorage gives you the best of both worlds: in-memory read speed with background persistence so your data survives container restarts.

Lambda Execution Architecture

Lambda is the most complex service in Floci. Functions run inside real Docker containers, not a JavaScript VM or mock interpreter. This means your Node.js, Python, Java, Go, or Ruby functions run exactly as they would in production.

flowchart TD
    Invoke["Invoke API
:4566/2015-03-31/functions/fn/invocations"]
    Invoke --> WP["WarmPool
Container pool manager"]

    WP -->|container available| CE["ContainerExecutor"]
    WP -->|cold start needed| CL["ContainerLauncher"]
    CL -->|docker run| DC["Docker Container
(e.g. public.ecr.aws/lambda/nodejs:22)"]

    subgraph RAS ["RuntimeApiServer (Vert.x, port 9200+)"]
        direction LR
        Next["/runtime/invocation/next
← container polls here"]
        Resp["/runtime/invocation/id/response
← container posts result here"]
    end

    DC -->|Lambda Runtime bootstrap| Next
    CE --> Next
    Resp --> CE
    CE -->|result| Invoke

When an invocation arrives:

1. The WarmPool checks if a pre-warmed container exists for the function
2. If not, ContainerLauncher pulls the runtime image and starts a container
3. The container’s Lambda bootstrap polls /runtime/invocation/next on the embedded RuntimeApiServer
4. The invocation payload is delivered, the function executes, and the result is posted back
5. The container is returned to the warm pool for reuse

Floci vs LocalStack

Feature Comparison

AWS SDK Compatibility Test Results

Floci was benchmarked against LocalStack 4.14.0 using a suite of 408 AWS SDK v2 checks:

Performance Benchmarks

JVM vs Native Binary

Floci Native vs LocalStack Community

Quick Start

Docker (one command)

docker run --rm -p 4566:4566 hectorvent/floci:latest

Or use the JVM image:

docker run --rm -p 4566:4566 hectorvent/floci:latest-jvm

docker-compose (with Lambda + ElastiCache + RDS)

services:
  floci:
    image: hectorvent/floci:latest
    ports:
      - "4566:4566"
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
      - ./data:/app/data
    environment:
      FLOCI_STORAGE_MODE: hybrid
      FLOCI_STORAGE_PERSISTENT_PATH: /app/data
      FLOCI_SERVICES_DOCKER_NETWORK: myapp_default

Configure your AWS SDK

Point any AWS SDK to Floci by setting the endpoint URL and dummy credentials:

# AWS CLI
aws --endpoint-url http://localhost:4566 s3 mb s3://my-bucket
aws --endpoint-url http://localhost:4566 sqs create-queue --queue-name my-queue

# Environment variables (for SDK auto-discovery)
export AWS_ENDPOINT_URL=http://localhost:4566
export AWS_ACCESS_KEY_ID=test
export AWS_SECRET_ACCESS_KEY=test
export AWS_DEFAULT_REGION=us-east-1

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

Build from source

git clone https://github.com/hectorvent/floci.git
cd floci

# Dev mode with hot reload
mvn quarkus:dev

# JVM build
mvn clean package -DskipTests
java -jar target/quarkus-app/quarkus-run.jar

# Native binary (requires GraalVM / Mandrel)
mvn clean package -Dnative -DskipTests
./target/floci-runner

Region Isolation

Floci isolates resources by AWS region out of the box. SSM parameters, SQS queues, DynamoDB tables, and Lambda functions created in us-east-1 are completely independent from those in eu-west-1. S3 buckets follow AWS’s global bucket namespace model.

flowchart LR
    subgraph US ["us-east-1"]
        SSM1["SSM /prod/db-url"]
        SQS1["SQS orders-queue"]
        DDB1["DynamoDB users"]
    end

    subgraph EU ["eu-west-1"]
        SSM2["SSM /prod/db-url"]
        SQS2["SQS orders-queue"]
        DDB2["DynamoDB users"]
    end

    subgraph GL ["Global"]
        S3G["S3 my-bucket"]
    end

Why Not Just Use Mocks?

Unit-level mocks are fast but brittle — they test your code, not your integration with AWS. Floci lets you run real AWS SDK calls, real IAM policies, real event-source mappings (SQS → Lambda), and real API Gateway routing, all locally. When your CI environment runs the exact same stack as production, “it works on my machine” becomes “it works, period.”

What’s Next

Floci is actively developed. Since the initial release, CloudFormation stacks, Step Functions, DynamoDB Streams, Kinesis, Cognito, KMS, Secrets Manager, EventBridge, CloudWatch Logs and Metrics, API Gateway v2, and expanded IAM/STS coverage have all landed. Contributions are welcome at github.com/hectorvent/floci.

Floci is MIT-licensed. No auth tokens. No usage limits. No surprises.