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.
docker run -d --name floci -p 127.0.0.1:4566:4566 \ floci/floci:2.2.0@sha256:e97cd0c1dc2aa14e7697fb5ef5018404c4d6345169dbd276315f0bed2c7b0520Create a compose.yaml file:
services: floci: container_name: floci image: floci/floci:2.2.0@sha256:e97cd0c1dc2aa14e7697fb5ef5018404c4d6345169dbd276315f0bed2c7b0520 ports: - "127.0.0.1:4566:4566"Then start it:
docker compose up -dCheck 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:
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:
export AWS_ENDPOINT_URL=http://localhost:4566export AWS_DEFAULT_REGION=us-east-1export AWS_ACCESS_KEY_ID=testexport AWS_SECRET_ACCESS_KEY=testThe 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:
aws s3 mb s3://lab-bucketecho "test content" > objet.txtaws s3 cp objet.txt s3://lab-bucket/objet.txtaws 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
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-tablesThe 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:
terraform initterraform apply -auto-approveaws s3 ls # terraform-drop-in appearsaws dynamodb list-tables # tf-table appearsTerraform 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.
docker rm -f floci 2>/dev/nulldocker 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:e97cd0c1dc2aa14e7697fb5ef5018404c4d6345169dbd276315f0bed2c7b0520services: floci: container_name: floci image: floci/floci:2.2.0@sha256:e97cd0c1dc2aa14e7697fb5ef5018404c4d6345169dbd276315f0bed2c7b0520 user: root ports: - "127.0.0.1:4566:4566" volumes: - /var/run/docker.sock:/var/run/docker.sockMounting /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).
aws ec2 run-instances \ --image-id ami-00000000 \ --instance-type t3.micro \ --count 1The 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:
aws ec2 describe-instances \ --query 'Reservations[].Instances[].[InstanceId,State.Name]' \ --output tableOnce 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_MODE | Behaviour | Use |
|---|---|---|
memory (default) | state in RAM, lost on stop | CI, throwaway tests |
persistent | immediate disk write on each mutation | maximum durability |
hybrid | RAM speed plus asynchronous flush every 5 s | long-running dev |
wal | write-ahead log | durability 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.
docker ps -aq --filter name=floci-aws- | xargs -r docker rm -fdocker rm -f flocidocker network ls -q --filter name=floci-aws- | xargs -r docker network rmunset AWS_ENDPOINT_URL AWS_ACCESS_KEY_ID AWS_SECRET_ACCESS_KEYThe 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.
| Symptom | Likely cause | Solution |
|---|---|---|
Could not connect to the endpoint URL | Container not ready or wrong port | Check docker ps and that port 4566 is mapped |
InvalidClientTokenId or identity errors | AWS variables not exported | Re-export AWS_ENDPOINT_URL and non-empty credentials |
| Terraform ignores the endpoint | endpoints block missing or service not listed | Add the service in the provider's endpoints { ... } |
An EC2 instance stays in pending | Docker socket not mounted or Floci not run as root | Restart with -u root -v /var/run/docker.sock:/var/run/docker.sock |
A service answers not implemented | API not covered by this version | Check 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_URLis enough to redirect AWS CLI and SDKs to the emulator- Terraform targets Floci through the
endpointsblock: IaC tested for free - EC2/ECS/Lambda/RDS/EKS: mount
/var/run/docker.sockand run Floci asrootso instances move torunning - Always pin a version (
tag@sha256form), neverlatest - 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.
Docker socket is not mounted: without it, Floci cannot start the container
that backs the instance. Start the container with
-u root -v /var/run/docker.sock:/var/run/docker.sock and the instance moves torunning.ground: one container on port 4566, the
memory storage mode bydefault and no cloud account. Pin the image in the
tag@sha256 form (version and digest).aws provider with anendpoints block pointing to http://localhost:4566, plusskip_credentials_validation, skip_requesting_account_id,skip_metadata_api_check and non-empty dummy credentials.127.0.0.1.