<p align="center">
<img src="docs/assets/floci-black.svg#gh-light-mode-only" alt="Floci" width="500" />
<img src="docs/assets/floci-white.svg#gh-dark-mode-only" alt="Floci" width="500" />
</p>
<p align="center">
<strong>Any Cloud. Locally.</strong><br />
Light, fluffy, and always free<br />
No account. No auth token. No feature gates. Just <code>docker compose up</code>.
</p>
<p align="center">
<a href="https://github.com/floci-io/floci/releases/latest"><img src="https://img.shields.io/github/v/release/floci-io/floci?label=latest%20release&color=blue" alt="Latest Release"></a>
<a href="https://github.com/floci-io/floci/actions/workflows/release.yml"><img src="https://img.shields.io/github/actions/workflow/status/floci-io/floci/release.yml?label=build" alt="Build Status"></a>
<a href="https://hub.docker.com/r/floci/floci"><img src="https://img.shields.io/docker/pulls/floci/floci?label=docker%20pulls" alt="Docker Pulls"></a>
<a href="https://hub.docker.com/r/floci/floci"><img src="https://img.shields.io/docker/image-size/floci/floci/latest?label=image%20size" alt="Docker Image Size"></a>
<a href="https://opensource.org/licenses/MIT"><img src="https://img.shields.io/badge/license-MIT-green" alt="License: MIT"></a>
<a href="https://github.com/floci-io/floci/stargazers"><img src="https://img.shields.io/github/stars/floci-io/floci?style=flat" alt="GitHub Stars"></a>
</p>
<p align="center">
<a href="#quick-start">Quick Start</a> ·
<a href="#features">Features</a> ·
<a href="#supported-services">Services</a> ·
<a href="#sdk-integration">SDKs</a> ·
<a href="#testcontainers">Testcontainers</a> ·
<a href="#migrating-from-localstack">Migration</a> ·
<a href="https://floci.io/floci/">Docs</a>
</p>
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.
<details>
<summary>Prefer Docker Compose?</summary>
Create a compose.yaml file:
services:
floci:
image: floci/floci:latest
ports:
- "4566:4566"
Start Floci:
docker compose up
Then configure your AWS environment manually:
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
</details>
<details>
<summary>Using the old <code>hectorvent/floci</code> image?</summary>
Update your image name:
# Before
image: hectorvent/floci:latest
# After
image: floci/floci:latest
The old hectorvent/floci repository no longer receives updates.
</details>
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
<details open>
<summary><strong>Local AWS without the cloud account</strong></summary>
Run AWS-compatible services locally without an AWS account, auth token, or paid feature gates.
</details>
<details>
<summary><strong>Real Docker where fidelity matters</strong></summary>
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.
</details>
<details>
<summary><strong>Drop-in AWS compatibility</strong></summary>
Point standard AWS clients at http://localhost:4566. Existing credentials, regions, SDKs, CLI commands, and IaC workflows stay familiar.
Terraform can provision AWS-shaped resources locally through Floci using the standard HashiCorp AWS provider. See the Terraform with Floci guide for provider configuration, resource examples, and optional emulated S3 state.
</details>
<details>
<summary><strong>Fast enough for CI</strong></summary>
The native image starts in milliseconds and keeps idle memory low, making it practical for local development and test pipelines.
</details>
<details>
<summary><strong>Configurable persistence</strong></summary>
Choose from in-memory, persistent, hybrid, and write-ahead log storage depending on the durability profile you need.
</details>
Why Floci?
LocalStack's community edition sunset in March 2026, requiring auth tokens and freezing security updates. Floci is the no-strings-attached alternative.
Broad AWS coverage. Free forever. See the Services Overview for the full list of emulated services.
Architecture Overview
flowchart LR
Client["AWS SDK / CLI"]
subgraph Floci ["Floci, port 4566"]
Router["HTTP Router\nJAX-RS / Vert.x"]
subgraph Stateless ["Stateless Services"]
A["SSM · SQS · SNS\nIAM · STS · KMS\nSecrets Manager · SES\nCognito · Kinesis\nEventBridge · Scheduler · AppConfig\nCloudWatch · Step Functions\nCloudFormation · ACM · Config · CloudTrail\nAPI Gateway · AppSync · ELB v2 · Auto Scaling\nElastic Beanstalk · CodeDeploy · CodePipeline · Backup · FIS · Bedrock Runtime · Bedrock AgentCore · Route53 · Transfer"]
end
subgraph Stateful ["Stateful Services"]
B["S3 · DynamoDB\nDynamoDB Streams"]
end
subgraph Containers ["Container Services"]
C["Lambda\nElastiCache\nRDS\nNeptune\nECS\nEC2\nMSK\nEKS\nOpenSearch\nCodeBuild\nManaged Flink"]
D["Athena -> floci-duck\nDuckDB sidecar"]
end
Router --> Stateless
Router --> Stateful
Router --> Containers
Stateless & Stateful --> Store[("StorageBackend\nmemory · hybrid · persistent · wal")]
end
Docker["Docker Engine"]
Client -->|"HTTP :4566\nAWS wire protocol"| Router
Containers -->|"Docker API\nIAM / SigV4 auth"| Docker
Supported Services
Floci supports local emulation for application services, data services, eventing, identity, infrastructure, billing, and container-backed workloads.
For operation-level compatibility, see the Services Overview.
<details>
<summary>Detailed service notes</summary>
</details>
Real Docker Integration
Floci uses real Docker containers when in-process emulation would reduce fidelity. This applies to stateful databases, connection-heavy protocols, runtimes, and build systems.
Docker-backed services require the Docker socket:
docker run -d --name floci \
-p 4566:4566 \
-v /var/run/docker.sock:/var/run/docker.sock \
-u root \
floci/floci:latest
Overriding default images
Persistence and Storage Modes
Floci can trade speed for durability depending on the workflow. Configure the default mode with FLOCI_STORAGE_MODE, or override storage per service.
Use memory for fast test runs. Use hybrid when you want state preserved across container restarts without much overhead.
For more detail, see the Storage Configuration documentation.
Multi-Account Isolation
Floci supports per-account resource isolation with no extra setup. If AWS_ACCESS_KEY_ID is exactly 12 digits, Floci uses it as the account ID. Resources created by one account are invisible to another.
AWS_ACCESS_KEY_ID=111111111111 aws sqs create-queue --queue-name orders
AWS_ACCESS_KEY_ID=222222222222 aws sqs create-queue --queue-name orders
Any other key format, such as test or AKIA..., causes Floci to fall back to FLOCI_DEFAULT_ACCOUNT_ID, which defaults to 000000000000.
STS temporary credentials are routed too: credentials from AssumeRole resolve to the assumed role's account, so the cross-account assume-role-then-provision pattern works locally. Resolution precedence is 12-digit AKID → temporary-session lookup → FLOCI_DEFAULT_ACCOUNT_ID.
See the Multi-Account Isolation docs.
SDK Integration
Point your existing AWS SDK at http://localhost:4566.
<details>
<summary><strong>Java, AWS SDK v2</strong></summary>
var client = DynamoDbClient.builder()
.endpointOverride(URI.create("http://localhost:4566"))
.region(Region.US_EAST_1)
.credentialsProvider(StaticCredentialsProvider.create(
AwsBasicCredentials.create("test
…(truncated)