Floci puts AWS-shaped services on localhost:4566, and its web console needs your Docker socket

One endpoint on port 4566 for every emulated service

Floci emulates selected AWS services on your machine and exposes all of them at a single address, http://localhost:4566. Your AWS SDK, the AWS CLI, Terraform, CDK, OpenTofu or a test suite only needs that endpoint to keep working as it does against real AWS. There is no account to create, no auth token to fetch and no paid feature gate.

Any published AWS region works, in every partition, and credentials can be any non-empty values unless you explicitly enable stricter service-specific auth checks. That default makes local setup quick, but it also means a test suite passes with credentials that real AWS would reject. Code paths that depend on IAM denials or bad keys need those stricter checks turned on, or they will not be exercised at all.

Floci is the AWS member of a family of emulators: floci-az for Azure on port 4577, floci-gcp for GCP on 4588 and floci-oci for OCI on 4599. The project is MIT licensed and written in Java.

Three ways to start it: floci CLI, standalone binary or Compose

The quickest route is the separate floci-cli tool:

floci start

It also writes the environment for your shell:

eval $(floci env)

After that, ordinary AWS commands go to the emulator:

aws s3 mb s3://my-bucket

aws dynamodb list-tables

Without Docker, each release ships a standalone floci-aws binary for Linux, macOS and Windows. With Docker Compose, a compose.yaml that runs the floci/floci:latest image and maps 4566:4566 is enough to bring it up with docker compose up. The Compose route does not export anything for you, so you set the variables by hand:

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 latest tag moves with each release; recent ones are 2.2.0, 2.3.0 and 2.4.0, the last on 31 October 2026. Pin a tag in CI if you want runs to stay comparable.

The hectorvent/floci image has stopped receiving updates

Floci used to publish under hectorvent/floci. That repository no longer receives updates, and the image name to use now is floci/floci:latest. The change is a one-line edit in a Compose file:

# Before
image: hectorvent/floci:latest

# After
image: floci/floci:latest

The consequence of missing this is quiet: an old Compose file keeps pulling a working image, so nothing breaks, but none of the releases since the move arrive. Anyone who copied a Compose snippet from an older blog post or internal wiki should check the image line.

The same applies to LocalStack users. Floci presents itself as a drop-in replacement where you swap the image and keep going, with a dedicated migration section in its documentation. Because Floci emulates a selected set of services, the swap is only safe once you have confirmed the services your stack touches are on its list.

The web console starts a sidecar container on first request

Floci has a browser console for inspecting resources at http://localhost:4566/_floci/ui. Nothing runs at boot. The first request pulls the console image, starts it as a sidecar on Floci's Docker network, passes it Floci's reachable address and the standard AWS environment, polls its health endpoint, and redirects the browser once the sidecar reports it can reach Floci. Its logs stream into CloudWatch Logs under /floci/ui.

Starting a container requires mounting the Docker socket into Floci:

    volumes:
      - /var/run/docker.sock:/var/run/docker.sock

That is the real cost of the console. A container with the Docker socket can start other containers on the host, which some CI systems and security policies forbid. The first visit also waits for an image pull. The defaults are FLOCI_SERVICES_UI_ENABLED true, image floci/floci-ui:0.7.0, container name floci-ui and host port 4500. FLOCI_SERVICES_UI_BIND_ADDRESS is unset, which publishes the console on every interface; set it to 127.0.0.1 when Floci's own port is loopback-only, or the console ends up more exposed than the emulator. FLOCI_SERVICES_UI_KEEP_RUNNING_ON_SHUTDOWN defaults to false.

Any image that follows the console contract can replace the UI

The bundled console is replaceable. A console that listens on the port in PORT, serves GET /api/health and talks to Floci at AWS_ENDPOINT_URL runs with nothing more than an image name:

environment:
  FLOCI_SERVICES_UI_IMAGE: acme/my-console:1.0

Consoles that differ from those defaults declare it through io.floci.console.* image labels. Older images without labels need the differences spelled out. StackPort listens on 8080 rather than 4500, so it needs FLOCI_SERVICES_UI_PORT and FLOCI_SERVICES_UI_INTERNAL_PORT set to "8080". Floci Dash honours PORT but expects the endpoint in FLOCI_URL and serves health at /api/healthz, so it sets FLOCI_SERVICES_UI_ENDPOINT_ENV and FLOCI_SERVICES_UI_STATUS_PATH instead.

The endpoint is never configured by hand. Floci resolves its own reachable address at start time and injects it, which avoids the usual mistake of pointing a sidecar at localhost and reaching itself instead of the emulator.

The repository's Compose file opens far more than port 4566

The docker-compose.yml at the repository root is not the minimal quick-start file. It builds from docker/Dockerfile and publishes 4566 plus the ranges 6379-6399, 7001-7099 and 9200-9299, with FLOCI_SERVICES_RDS_PROXY_BASE_PORT set to 7001. It mounts the Docker socket and ./data, sets FLOCI_HOSTNAME to floci, FLOCI_BASE_URL to http://floci:4566, and turns on FLOCI_SERVICES_LAMBDA_HOT_RELOAD_ENABLED and FLOCI_TLS_ENABLED. With TLS on, HTTP and HTTPS share port 4566 through first-byte sniffing, so no extra mapping is needed.

It also uses localhost.floci.io as the ElastiCache announce hostname. That name resolves through public DNS to 127.0.0.1 on the host and, inside Compose, to the network alias on floci_default, so clients on both sides reach the same cluster. The file mirrors the CI compatibility workflow, which makes it useful for reproducing a CI failure locally and heavier than needed for everyday use.

Persistence moved to named Docker volumes

FLOCI_STORAGE_HOST_PERSISTENT_PATH is no longer needed, because Floci now stores data in named Docker volumes by default. If you relied on that variable to keep state between restarts, find the volumes Floci created with:

docker volume ls -f label=floci=true

The practical effect is that data no longer lands in a host directory you chose, so backing it up or wiping it means working with Docker volumes rather than deleting a folder.

Under the hood, request shapes for several services, including DynamoDB, SES v2, API Gateway, ECS, ECR and Redshift Serverless, are generated from botocore's published models by scripts in tools/aws, and partition data comes from botocore's partition metadata. Supported Actions tables in docs/services are generated from handler source, and the service matrix is checked against the registered service catalog so a service cannot ship undocumented. The last push landed on 2 November 2026.

Editorial conclusion

Floci fits developers and CI pipelines that need S3, DynamoDB and other AWS-shaped APIs on a laptop or runner without an AWS account, token or paid tier, and teams leaving LocalStack who want to try an image swap first. It is the wrong choice when tests must prove IAM or credential handling, since any non-empty credentials pass by default, or when mounting the Docker socket is off the table. Before adopting it, check that every AWS service and action your code calls is emulated, pin a release such as 2.4.0 instead of latest, and move off the hectorvent/floci image if you still use it.

Frequently asked questions

Official sources

1. Official documentation
2. Official README
3. Project repository
4. Release notes