floci-io/floci

Light, fluffy, and always free - The AWS Local Emulator alternative

Summary

Floci is a free, open-source local AWS emulator written in Java that exposes AWS-compatible services at http://localhost:4566. Developers can point existing AWS SDKs, CLI commands, Terraform, CDK, OpenTofu, and test suites at this endpoint without an AWS account or auth token; the README describes it as a drop-in replacement for LocalStack.

What it is useful for

Use Floci for local feature development, automated tests, and CI when code depends on AWS services. A developer can exercise S3 object handling, DynamoDB tables, SQS queues, SNS subscriptions, and Lambda execution locally while keeping familiar CLI calls and SDK configuration. Terraform can provision AWS-shaped resources through Floci with the standard HashiCorp AWS provider; CDK and OpenTofu workflows can target the same endpoint.

Some workloads use real Docker-backed execution rather than shallow mocks, including Lambda, RDS, Neptune, ElastiCache, MSK, ECS, EC2, EKS, OpenSearch, CodeBuild, and Managed Service for Apache Flink. Storage can be in-memory, persistent, hybrid, or write-ahead-log based on the durability needed.

Support is not uniform across services. Bedrock Runtime returns dummy responses, Bedrock AgentCore returns canned responses, QuickSight has no SQL execution, SPICE processing, or BI visualization, and AWS FIS simulates experiments without injecting faults into other services. Check the README’s Services Overview before depending on a particular operation.

How engineers can use it

For Docker Compose, create a compose.yaml with the documented image and port mapping:

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

Start the emulator:

docker compose up

Configure the standard AWS environment variables:

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

Then use existing AWS CLI commands, for example:

aws s3 mb s3://my-bucket

aws dynamodb create-table \
  --table-name demo-table \
  --attribute-definitions AttributeName=pk,AttributeType=S \
  --key-schema AttributeName=pk,KeyType=HASH \
  --billing-mode PAY_PER_REQUEST

Local tests or CI jobs can use the same endpoint and non-empty credentials unless stricter service-specific authentication checks are enabled.

The README also documents floci start followed by eval $(floci env). Installing that separate CLI is not explained in this repository, so consult the README’s CLI instructions for that route.

For resource inspection, open http://localhost:4566/_floci/ui. In the Compose setup, the console sidecar starts on the first request and requires mounting the Docker socket.