Floci: a local AWS emulator you run with docker compose up

What Floci replaces, and who it is for

The problem is the loop between writing cloud code and running it. A developer changes a DynamoDB call, and to see whether it works they need an AWS account, credentials, a region, and a bill. Floci removes that loop by running AWS-shaped services on the local machine. The README states the intent plainly: it gives you AWS services "without requiring a cloud account, an auth token, or paid feature gates", and you point your SDK, CLI, Terraform, CDK, OpenTofu or test suite at http://localhost:4566.

The audience is narrower than "anyone using AWS". It is developers who already have AWS-shaped code and want to execute it locally, and CI pipelines that need a service endpoint inside a job. The README also frames the project against LocalStack's community edition, which it says sunset in March 2026 and now requires auth tokens with frozen security updates. Floci is positioned as the no-account alternative, and the licence is MIT.

The project is not archived and the last push was on 2026-08-18, with release 1.7.0 published the same day. That is recent enough that the code is moving, but it also means the surface is still changing between minor versions.

The request path: one port, a router, and Docker-backed services

Everything arrives on port 4566. The architecture diagram in the README shows an HTTP router built on JAX-RS and Vert.x sitting in front of two groups of services. The first group is stateless and handles the protocol-level work: SSM, SQS, SNS, IAM, STS, KMS, Secrets Manager, SES, Cognito, Kinesis, EventBridge, Scheduler, AppConfig, CloudWatch, Step Functions, CloudFormation, ACM, Config, CloudTrail, API Gateway, AppSync, ELB v2, Auto Scaling, Elastic Beanstalk, CodeDeploy, CodePipeline, Backup, FIS, the Bedrock entries, Route53 and Transfer.

The second group is stateful, and this is where the design diverges from a pure mock. The README says Lambda, RDS, Neptune, ElastiCache, MSK, ECS, EC2, EKS, OpenSearch, CodeBuild and Managed Service for Apache Flink use "real Docker-backed execution instead of shallow mocks". So a Lambda invocation is not a canned response; the emulator starts a container. The repository's docker-compose.yml confirms the dependency by mounting /var/run/docker.sock into the Floci container. Without that socket, the Docker-backed services have nothing to talk to.

The compose file also publishes ranges beyond 4566: 6379-6399, 7001-7099 and 9200-9299. Those correspond to the Redis-style and OpenSearch-style services and to the RDS proxy base port, which the file sets through FLOCI_SERVICES_RDS_PROXY_BASE_PORT. The same file sets FLOCI_SERVICES_DOCKER_NETWORK to floci_default and adds a network alias of localhost.floci.io, with a comment explaining that localhost.floci.io resolves to 127.0.0.1 on the host and to the container inside Compose. That alias exists so services which hand a hostname back to a client (an ElastiCache cluster, for example) return something the client can actually reach.

Storage is configurable. The README lists in-memory, persistent, hybrid and write-ahead log modes, and the compose comments note a migration away from FLOCI_STORAGE_HOST_PERSISTENT_PATH toward named Docker volumes labelled floci=true.

Installing Floci and running a first DynamoDB table

The README gives two paths. The quickest is the official CLI from the floci-io/floci-cli repository:

floci start

Then export the environment the CLI produces, which sets the endpoint and dummy credentials for the current shell:

eval $(floci env)

After that, ordinary AWS CLI commands go to the emulator. The README's own example creates a bucket and a table, then lists the tables:

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

You should see the new table name echoed back by list-tables. The README notes that any region works and that credentials can be any non-empty values unless you explicitly enable stricter service-specific auth checks.

If you prefer Compose, the README's minimal file is three lines of service definition. The repository's own docker-compose.yml is the fuller version, and it is the one to copy if you want the Docker-backed services to work:

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

With the minimal file you configure the client yourself. The README lists AWS_ENDPOINT_URL, AWS_DEFAULT_REGION, AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY as the variables to export, with the region set to us-east-1 and both key values set to test. One migration note worth reading before you copy an old file: the image moved from hectorvent/floci to floci/floci, and the README says the old repository no longer receives updates.

Where the emulator stops being AWS

An emulator is a promise about behaviour, and the promise has edges. The most visible edge is authentication. The README says credentials can be any non-empty value unless stricter service-specific auth checks are enabled, which means the default configuration does not evaluate IAM policies the way AWS does. A test that asserts an AccessDenied for a specific principal will not exercise the same code path locally. IAM and STS are both in the supported list, so the APIs exist, but the README does not claim policy enforcement parity.

The second edge is Docker. Any service in the Docker-backed group needs the container runtime, and the compose file's socket mount is the mechanism. On a machine without Docker, or in a CI runner that does not allow socket mounts, those services are unavailable even though Floci itself starts. The README does not document a fallback for that case.

The third edge is coverage. The README claims 83 services, and the repository enforces that claim in an unusual way: the Makefile's docs-check target regenerates the action tables from handler source and fails if the Service Matrix in docs/services/index.md drifts from ResolvedServiceCatalog.java. That gate tells you a service is registered and documented; it does not tell you every action within the service is implemented. If your code calls an action that is not in the per-service Supported Actions table, that is the thing to check before you build a pipeline on it.

Finally, the release cadence matters for anyone pinning versions. Three releases landed between 2026-07-29 and 2026-08-18. That is a fast-moving project, and the compose file itself carries a comment about an environment variable that is "no longer needed", which is the kind of churn you should expect when you upgrade.

Floci and LocalStack: the actual difference in approach

The README's comparison table is the project's own, so read it as a claim rather than a measurement. It reports startup around 24 ms against roughly 3.3 s, idle memory around 13 MiB against roughly 143 MiB, and an image around 90 MB against roughly 1.0 GB. Those numbers are the project's, and the README does not describe the machine or the method behind them.

The more interesting difference is architectural. LocalStack's community edition, as the README describes it, requires an auth token and has frozen security updates. Floci requires neither. Beyond licensing, the two differ in how they treat the hard services. The README's table marks API Gateway v2, Cognito, RDS, ElastiCache, MSK, Neptune, DocumentDB, ECS, EC2, EKS and CodeBuild as present in Floci and absent from LocalStack Community, and describes Floci's versions of those as real Docker rather than mocks.

That is a real design fork. Running a container per Lambda invocation or per RDS instance buys fidelity and costs startup latency and host resources, which is precisely why the project also ships a native binary and a small base image. The trade is deliberate: cheap for the stateless services, expensive where the semantics are hard to fake. If your workload is S3, SQS and DynamoDB, you are paying for an architecture you are not using. If your workload includes a Lambda that talks to an RDS instance, the container-backed path is the reason to pick this over a lighter mock.

Licence, upgrade cost, and what the repository maintains

Floci is MIT licensed, and the README's headline is that it is free with no feature gates. MIT is permissive, so the practical implication for adopters is that you can vendor, modify and redistribute it, subject to keeping the copyright notice. That is a statement about the licence text, not legal advice; if you plan to redistribute a modified build, have someone qualified read the LICENSE file in the repository root.

The maintenance surface is larger than the Java source. The repository root holds a Makefile, a docs directory, a tools directory, compatibility-tests, sidecars and overrides. The Makefile defines docs-sync, docs-check and docs-test, and docs-check is a CI gate that regenerates the action tables and the CloudFormation resource-type table, fails if either is stale, fails if the Service Matrix is out of sync, and fails if any doc names a -jvm image tag, because the release workflow publishes only x.y.z, latest and their -compat twins. For a contributor that means documentation edits are part of the change, not an afterthought. For an adopter it means the per-service docs are generated from handler source, which is a better signal than prose that drifts.

The upgrade cost is the usual one for a fast-moving emulator. The image name changed once already, an environment variable was retired in favour of named volumes, and three releases shipped in about three weeks. Pin a tag rather than tracking latest, and read CHANGELOG.md between bumps.

Editorial conclusion

Adopt Floci if you need S3, DynamoDB, SQS, Lambda or RDS behaviour on a laptop or in a CI job and you are willing to accept an emulator's fidelity limits; the CLI and the compose file both get you to port 4566 in minutes. Do not adopt it if your tests depend on exact AWS error semantics, on IAM policy evaluation, or on services the supported list does not name. Before you commit, run your own suite against it: check that the specific actions you call appear in the per-service Supported Actions tables under docs/services, and confirm the container can reach /var/run/docker.sock, because every Docker-backed service depends on that mount.

Frequently asked questions

Official sources

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