Guide · Open source

How to use Floci: run a local AWS emulator with Docker

Updated 2026-10-29 · written with AI from the project's own documentation and checked against our catalogue data

Floci is a free, MIT-licensed local AWS emulator written in Java. It runs AWS-shaped services on your own computer so you can develop and test cloud code without a real AWS account. This guide shows you how to start it, point your existing AWS tools at it, and know where its limits are.

Flocifloci-io/floci · ★ 27.7k · MIT Install options & downloads

Quick start

1Install Docker. Docker is required for the Docker Compose path. Make sure it is installed and running on your machine.
2Create a compose file. Create a compose.yaml that runs floci/floci:latest and maps port 4566.
3Start Floci. Run docker compose up to start the emulator.
4Set AWS environment variables. Point AWS_ENDPOINT_URL at http://localhost:4566 and set a region and non-empty credentials.
5Run AWS commands. Use the AWS CLI, an SDK or Terraform as normal and check the results with commands such as aws dynamodb list-tables.

What Floci does and who it is for

Floci gives you AWS-style services on your machine. You point your AWS SDK, CLI, Terraform, CDK, OpenTofu or test suite at http://localhost:4566 and your existing workflows keep working.

It suits developers who want to test AWS code locally without cloud costs, and teams running automated tests or CI pipelines. It is a poor fit if you need exact behavior matching real AWS in every edge case, since it is an emulator and the README does not claim full parity.

Good fit: local development, automated tests, CI pipelines, Terraform, CDK and OpenTofu testing
Good fit: people migrating from LocalStack, which the README describes as a drop-in replacement
Not a fit: teams that need exact real-AWS behavior in every edge case
Not a fit: machines where you cannot run Docker or the Floci CLI

Install Floci with Docker Compose

Docker is the prerequisite for the Docker Compose path. The README's install command is shown below. Run it from the directory that contains your compose file.

If you prefer a compose file of your own, create a compose.yaml that maps port 4566. The README's example uses the official floci/floci:latest image.

Install Docker on your machine
Create a compose.yaml file with the floci service and the 4566:4566 port mapping
Run the start command

docker compose up

Start Floci with the CLI or a native binary

The README's fastest route is the official Floci CLI. Run floci start, then export the AWS environment variables with eval $(floci env).

If you cannot use Docker, each release ships a standalone floci-aws binary for Linux, macOS and Windows. The README links to its installation page for details.

floci start
eval $(floci env)

Configure your AWS environment manually

If you started Floci with Docker Compose, set the AWS environment variables yourself. The endpoint is http://localhost:4566 and the region in the example is us-east-1. The README says credentials can be any non-empty values unless you enable stricter service-specific auth checks.

Once these variables are set, standard AWS tools send their requests to Floci instead of to AWS.

AWS_ENDPOINT_URL points at Floci
AWS_DEFAULT_REGION is set to us-east-1 in the example
AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY can be any non-empty value such as test

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

Run your first AWS CLI commands against Floci

With the environment set, use the AWS CLI as you normally would. The README example creates an S3 bucket, creates a DynamoDB table with a partition key named pk, and lists the tables.

Any published AWS region works in every partition, according to the README.

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

aws dynamodb list-tables

Use Floci with Terraform, CDK and CI

The README says Terraform can provision AWS-shaped resources locally through Floci using the standard HashiCorp AWS provider. A Terraform guide is linked from the project's docs for provider configuration and examples.

For automated tests, the README lists a Testcontainers integration and SDK integration sections. Floci's native image is described as starting in milliseconds with low idle memory, which suits test pipelines.

Terraform: use the standard HashiCorp AWS provider pointed at Floci
Tests: run Floci as part of your pipeline and send SDK calls to localhost:4566
Migrating from LocalStack: swap the image and keep your workflow, per the README

Open the web console (optional)

Floci ships a browser console for inspecting local resources. It is opened at http://localhost:4566/_floci/ui. The first request starts the console as a sidecar container, which needs the Docker socket mounted into the Floci service.

The README lists variables that control the console, including FLOCI_SERVICES_UI_ENABLED, which defaults to true, and FLOCI_SERVICES_UI_PORT, which defaults to 4500.

Open http://localhost:4566/_floci/ui in your browser
Mount /var/run/docker.sock if you want the console to start

services:
  floci:
    image: floci/floci:latest
    ports:
      - "4566:4566"
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock

What people use it for

Creating and listing S3 buckets and DynamoDB tables during local development
Running automated tests against AWS-shaped services in a CI pipeline
Testing Terraform, CDK or OpenTofu configurations before deploying to a real account
Migrating a test setup from LocalStack by swapping the image, as the README describes

Frequently asked questions

Is Floci free to use?

The README says Floci is always free, with no account, no auth token and no paid feature gates. The project is MIT licensed.

What do I need to run Floci?

The README lists Docker as the prerequisite for the Docker Compose path. A standalone floci-aws binary is also available from releases for Linux, macOS and Windows, and the Floci CLI is the fastest route.

How do I install Floci?

Use docker compose up with a compose.yaml that runs floci/floci:latest on port 4566. Alternatively, install the official Floci CLI and run floci start.

Do I need a real AWS account to use Floci?

No. The README says Floci requires no account. Credentials can be any non-empty values unless you enable stricter service-specific auth checks.

Can Floci replace LocalStack?

The README describes Floci as a drop-in replacement for LocalStack: you swap the image and keep going. Check the migration section of the README for details on your setup.

Does Floci behave exactly like real AWS?

No guarantee is given. Floci is an emulator, and the README does not claim full parity with AWS in every edge case, so test critical behavior against real AWS where it matters.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

Floci suits developers and CI pipelines that want to run AWS-style code locally at no cost, especially if you use the AWS CLI, SDKs, or Terraform and can run Docker. If you need exact real-AWS behavior in every edge case, or you cannot run Docker or the Floci CLI, consider LocalStack, Moto, ElasticMQ or MinIO instead.

Install options & downloads