Skip to content
Français
Account: not signed in, sync available My learning
Select theme
Français
Lire en français

Floci: emulate AWS locally to develop and test

15 min read
Improve this page

Logo Floci

Floci is an open-source (MIT licence) local AWS emulator that exposes AWS services on your machine, with no cloud account, no authentication token and nothing to pay. You point your AWS CLI, your SDKs, Terraform or OpenTofu at http://localhost:4566 and your tools work as against the real AWS. This guide shows how to start Floci with Docker, plug in your existing tools, and validate everything on S3, DynamoDB and a Terraform deployment. Target audience: developers and DevOps engineers who want a reproducible AWS environment for development, tests and CI.

What you will learn

  • Start Floci with Docker (pinned image, never latest)
  • Configure the local AWS environment (endpoint, region, credentials)
  • Use AWS CLI and Terraform against the emulator
  • Start real EC2 instances through the Docker socket
  • Understand the real scope and the limits of the emulation

Why a local AWS emulator

Developing directly against the real AWS costs money, requires an account and credentials, and makes tests slow and fragile (network latency, shared state, cleanup to do). A local emulator gives "AWS-compatible" services on your workstation: instant creation, total isolation, zero bill, and a CI that depends neither on an account nor on cloud availability.

Floci fills this niche just as LocalStack, the historical emulator, closed free access to its Community edition. Since version 2026.03.0 (March 2026), the single localstack/localstack image requires an authentication token tied to an account (a free plan exists for individual use), and the old open-source repository was archived (LocalStack announcements of March 2026). Floci positions itself as the MIT alternative, with no account and no token.

Prerequisites

  • Docker installed and running (docker --version).
  • The AWS CLI v2 (aws --version) for the command-line examples.
  • Optional: Terraform or OpenTofu for the infrastructure-as-code part.

Start Floci

Floci runs as a simple container listening on port 4566, the same one as LocalStack. Never use the latest tag: pin a precise version for reproducible environments.

Terminal window
docker run -d --name floci -p 127.0.0.1:4566:4566 \
floci/floci:2.2.0@sha256:e97cd0c1dc2aa14e7697fb5ef5018404c4d6345169dbd276315f0bed2c7b0520

Check that the container is ready. The image is native (Quarkus). Without the Docker socket mounted, Floci first tries to reach the Docker daemon and retries several times: allow about fifteen seconds before the Listening on line, and wait for it before running your AWS commands (otherwise the AWS CLI answers Connection was closed). With the socket mounted (EC2 section below), startup takes less than a second:

Terminal window
docker logs floci | grep 'Listening on'

The output should show a line like floci 2.2.0 native ... started ... Listening on: http://0.0.0.0:4566. The address 0.0.0.0 is the one inside the container; on the host side, docker port floci must answer 4566/tcp -> 127.0.0.1:4566, a sign that the port is not exposed to the network.

The commands in this guide combine the human-readable tag 2.2.0 and the digest @sha256:..., which freezes the exact content of the image: a tag alone can be repointed to another image, the digest cannot. This tag@sha256 form is the one to reproduce in your CI for a controlled supply chain.

Plug in your AWS tools

Floci accepts any non-empty credentials and any region. Export the AWS environment once and for all in your shell:

Terminal window
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 AWS_ENDPOINT_URL variable is the key: it redirects the AWS CLI v2 and most SDKs to the emulator, without touching your application code.

First test with S3

Create a bucket, upload an object, list the result:

Terminal window
aws s3 mb s3://lab-bucket
echo "test content" > objet.txt
aws s3 cp objet.txt s3://lab-bucket/objet.txt
aws s3 ls s3://lab-bucket/

The output should list objet.txt with its size. You have just used the S3 API without an AWS account and without a single byte sent to the cloud.

A stateful service: DynamoDB

Terminal window
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

The table moves to the ACTIVE state and appears in list-tables. The state is kept as long as the container runs.

Deploy with Terraform

The main point of an emulator is to test your infrastructure as code without provisioning anything real. You configure Terraform's AWS provider to target Floci, through the endpoints block and a few options that disable the identity checks that are useless locally.

terraform {
required_providers {
aws = {
source = "hashicorp/aws"
version = "~> 6.0"
}
}
}
provider "aws" {
region = "us-east-1"
access_key = "test"
secret_key = "test"
skip_credentials_validation = true
skip_requesting_account_id = true
skip_metadata_api_check = true
s3_use_path_style = true
endpoints {
s3 = "http://localhost:4566"
dynamodb = "http://localhost:4566"
}
}
resource "aws_s3_bucket" "lab" {
bucket = "terraform-drop-in"
}
resource "aws_dynamodb_table" "lab" {
name = "tf-table"
billing_mode = "PAY_PER_REQUEST"
hash_key = "id"
attribute {
name = "id"
type = "S"
}
}

Deploy then check:

Terminal window
terraform init
terraform apply -auto-approve
aws s3 ls # terraform-drop-in appears
aws dynamodb list-tables # tf-table appears

Terraform prints Apply complete! Resources: 2 added, and the AWS CLI confirms that the resources exist on the Floci side. Your Terraform module is validated without an AWS account, for free, in a few seconds.

Start real EC2 instances

An EC2 instance created on Floci stays in the pending state as long as the emulator cannot run it. For it to move to running, mount the Docker socket into the Floci container and run it as root: RunInstances then creates a real Linux container per instance, with SSH key injection, UserData execution and IMDS support.

This is the same prerequisite for all of Floci's containerised services: EC2, ECS, Lambda, RDS and EKS rely on real Docker execution, not on simple stubs (mocks). S3 and DynamoDB do not need it.

Terminal window
docker rm -f floci 2>/dev/null
docker run -d --name floci \
-p 127.0.0.1:4566:4566 \
-u root \
-v /var/run/docker.sock:/var/run/docker.sock \
floci/floci:2.2.0@sha256:e97cd0c1dc2aa14e7697fb5ef5018404c4d6345169dbd276315f0bed2c7b0520

Mounting /var/run/docker.sock gives Floci control of the host's Docker daemon to start the backing containers; the -u root option (or user: root in Compose) gives it the rights to access the socket.

Create an instance. Floci ignores the AMI provided and falls back to its default image public.ecr.aws/amazonlinux/amazonlinux:2023: any ami-xxxxxxxx will do (the log then shows Unknown AMI ID ...; falling back to default image).

Terminal window
aws ec2 run-instances \
--image-id ami-00000000 \
--instance-type t3.micro \
--count 1

The move to running is not instantaneous: Floci creates then starts the backing container (SSH key injection, IMDS), which takes a few seconds. Let the transition happen before checking the state:

Terminal window
aws ec2 describe-instances \
--query 'Reservations[].Instances[].[InstanceId,State.Name]' \
--output table

Once the instance is running, docker ps lists the floci-aws-ec2-<id> container that carries it, with an SSH port exposed on the host. On the Terraform side, just add ec2 (and the other wanted services) to the provider's endpoints block:

endpoints {
ec2 = "http://localhost:4566"
s3 = "http://localhost:4566"
dynamodb = "http://localhost:4566"
}

Keep the state between two runs

By default, Floci keeps the state in memory (FLOCI_STORAGE_MODE=memory): everything disappears when the container stops, which is perfect for CI. To get your resources back after a restart, choose a persistent mode:

FLOCI_STORAGE_MODEBehaviourUse
memory (default)state in RAM, lost on stopCI, throwaway tests
persistentimmediate disk write on each mutationmaximum durability
hybridRAM speed plus asynchronous flush every 5 slong-running dev
walwrite-ahead logdurability without loss

The persistence directory is set with FLOCI_STORAGE_PERSISTENT_PATH (default ./data).

Scope and limits

Floci claims a broad coverage of AWS services. Some, such as Lambda, RDS, ECS, EC2 or EKS, rely on real Docker execution rather than on simple stubs (mocks), while S3 and DynamoDB keep a state (in memory by default, persistent depending on the storage mode seen above). This approach brings the emulator's behaviour closer to the real AWS for containerised services. These services require the Docker socket mount seen above: without it, an EC2 instance stays stuck in pending.

Two points of vigilance, specific to any emulator and accentuated by the project's youth:

  • The depth of an emulated API does not always equal AWS's: an advanced feature may be missing or differ.
  • Maintenance rests on a recent project: pin your versions and follow changes before making it a critical building block of your CI.

How do you clean up the Floci environment?

To reset everything, remove the container then unset the variables exported in your terminal, otherwise your AWS tools would keep targeting the localhost:4566 emulator or using the dummy credentials. With Docker Compose, docker compose down plays the role of docker rm -f floci.

Terminal window
docker ps -aq --filter name=floci-aws- | xargs -r docker rm -f
docker rm -f floci
docker network ls -q --filter name=floci-aws- | xargs -r docker network rm
unset AWS_ENDPOINT_URL AWS_ACCESS_KEY_ID AWS_SECRET_ACCESS_KEY

The backing containers (for example floci-aws-ec2-<id> for an EC2 instance) survive the removal of floci: the first line removes them, and the third deletes the floci-aws-vpc-... network that Floci created. Without them, docker compose down reports Resource is still in use on the Compose network.

Check with docker ps -a that no floci container remains, and with env | grep AWS_ that neither AWS_ENDPOINT_URL nor the access keys remain exported (AWS_DEFAULT_REGION, harmless, may stay).

Troubleshooting

This table is for diagnosing an error starting from what you see. Find the symptom in the first column, check the likely cause, then apply the solution in the last column before looking further.

SymptomLikely causeSolution
Could not connect to the endpoint URLContainer not ready or wrong portCheck docker ps and that port 4566 is mapped
InvalidClientTokenId or identity errorsAWS variables not exportedRe-export AWS_ENDPOINT_URL and non-empty credentials
Terraform ignores the endpointendpoints block missing or service not listedAdd the service in the provider's endpoints { ... }
An EC2 instance stays in pendingDocker socket not mounted or Floci not run as rootRestart with -u root -v /var/run/docker.sock:/var/run/docker.sock
A service answers not implementedAPI not covered by this versionCheck the Floci version, pin a compatible version

Key takeaways

  • Floci emulates AWS locally (MIT), on http://localhost:4566, with no account or token
  • It arrives as LocalStack Community switches to authenticated access (since March 2026)
  • AWS_ENDPOINT_URL is enough to redirect AWS CLI and SDKs to the emulator
  • Terraform targets Floci through the endpoints block: IaC tested for free
  • EC2/ECS/Lambda/RDS/EKS: mount /var/run/docker.sock and run Floci as root so instances move to running
  • Always pin a version (tag@sha256 form), never latest
  • Emulation speeds up dev, tests and CI, but does not replace a real validation before production

FAQ

This section gathers the frequently asked questions about Floci and its use as a local AWS emulator. Each question gets a short answer, to be completed by the previous chapters if the topic concerns you.

Next steps