floci-io / floci

Any Cloud. Locally.
Light, fluffy, and always free
No account. No auth token. No feature gates. Just docker compose up.

Quick Start · Features · Services · SDKs · Testcontainers · Migration · Docs

What is Floci?

Floci is a free, open-source local AWS emulator for development, testing, and CI.

It gives you AWS-shaped services on your machine without requiring a cloud account, an auth token, or paid feature gates. Point your AWS SDK, CLI, Terraform, CDK, OpenTofu, or test suite at http://localhost:4566 and keep your existing workflows.

Already using LocalStack? Floci is a drop-in replacement: swap the image and keep going. See Migrating from LocalStack.

Floci is the AWS member of the Floci emulator family, named after floccus, the cloud formation that looks like popcorn.

Quick Start

The fastest way to run Floci is with the official CLI

floci start

Export the AWS environment variables:

eval $(floci env)

Use your existing AWS tools normally:

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

Watch it run

This short demo shows the CLI flow: start Floci, export the local AWS environment, run standard AWS CLI commands, and stop the emulator.

https://github.com/user-attachments/assets/b55714dc-ef36-40ae-a734-cd2cadc288a8

All AWS services are available at http://localhost:4566. Any published AWS region works, in every partition. Credentials can be any non-empty values unless you explicitly enable stricter service-specific auth checks.

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

docker compose up

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

# Before
image: hectorvent/floci:latest

# After
image: floci/floci:latest

Web Console

Floci ships a browser console for inspecting the resources in your local emulator.

Open it at: http://localhost:4566/_floci/ui

Nothing runs at boot. The first request pulls the console image, starts it as a sidecar container on Floci's Docker network, hands it Floci's own reachable address plus the standard AWS environment, polls its health endpoint, and redirects the browser once it reports it can reach Floci. The sidecar's port is bound by Docker, so it needs no ports: entry of your own, and its logs are streamed into CloudWatch Logs under /floci/ui.

Starting a container needs the Docker socket:

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

Running a different console

The console is not fixed to the one Floci ships. Any console implementing the Floci console contract runs with nothing but an image name: listen on the port in PORT, serve GET /api/health, talk to Floci at AWS_ENDPOINT_URL.

environment:
  FLOCI_SERVICES_UI_IMAGE: acme/my-console:1.0

A console that differs from the contract's defaults says so in its own io.floci.console.* image labels, so its operators do not have to. StackPort, for example, listens on 8080 rather than 4500; on an image that predates the labels, say it by hand:

environment:
  FLOCI_SERVICES_UI_IMAGE: davireis/stackport:latest
  FLOCI_SERVICES_UI_CONTAINER_NAME: floci-stackport
  FLOCI_SERVICES_UI_PORT: "8080"
  FLOCI_SERVICES_UI_INTERNAL_PORT: "8080"

Floci Dash is another. It honours PORT, so only the two things it does differ on need naming:

environment:
  FLOCI_SERVICES_UI_IMAGE: ghcr.io/ofsazib/floci-dash:latest
  FLOCI_SERVICES_UI_CONTAINER_NAME: floci-dash
  FLOCI_SERVICES_UI_ENDPOINT_ENV: FLOCI_URL
  FLOCI_SERVICES_UI_STATUS_PATH: /api/healthz

The endpoint itself is never configured by hand: Floci resolves its own reachable address at start time and injects it as AWS_ENDPOINT_URL.

Full reference: Web Console and Console Contract v1.

Features