floci-io/floci

Features

Run AWS-compatible services locally without an AWS account, auth token, or paid feature gates.

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.

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.

Quick Start

eval $(floci env)

Migrating from LocalStack

Floci is a drop-in replacement for LocalStack Community. The port, credentials, SDK configuration, and CLI endpoint pattern work the same way. Swap the image and keep going.

LocalStack environment variables are translated automatically:

Init scripts mounted under /etc/localstack/init/ run unchanged. The /localstack/init and /localstack/health endpoints are still served. Once the emulator is up, the log also ends with a LocalStack-style Ready. line, so tooling that watches the log for it, such as the default wait strategy of Testcontainers' LocalStackContainer, works unchanged. Set LOCALSTACKPARITY=false to opt out of automatic translation.

• LOCALSTACKHOST — FLOCIHOSTNAME
• PERSISTENCE=1 — FLOCISTORAGEMODE=persistent
• LAMBDADOCKERNETWORK — FLOCISERVICESLAMBDADOCKERNETWORK
• LAMBDAREMOVECONTAINERS=1 — FLOCISERVICESLAMBDAEPHEMERAL=true
• DEBUG=1 — QUARKUSLOGLEVEL=DEBUG

Configuration

All settings are overridable through environment variables with the FLOCI prefix.

• FLOCIPORT — 4566 — Port exposed by the Floci API
• FLOCIDEFAULTREGION — us-east-1 — Default AWS region
• FLOCIDEFAULTACCOUNTID — 000000000000 — Default AWS account ID
• FLOCIBASEURL — http://localhost:4566 — Base URL used when Floci returns service URLs
• FLOCIHOSTNAME — Unset — Hostname used in returned URLs when Floci runs inside Docker Compose
• FLOCISTORAGEMODE — memory — Storage mode: memory, persistent, hybrid, or wal
• FLOCISTORAGEPERSISTENTPATH — ./data — Directory used for persisted state
• FLOCISERVICESLAMBDAECRBASEURI — public.ecr.aws — ECR base URI used when pulling Lambda runtime images (legacy name FLOCIECRBASEURI still works)
• FLOCISERVICESS3ENFORCEAUTH — false — Enforce S3 public/private read access and reject unknown signed S3 access keys

Web Console

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

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.

• FLOCISERVICESUIENABLED — true — Enable the console sidecar
• FLOCISERVICESUIIMAGE — floci/floci-ui:0.7.0 — Console image to run
• FLOCISERVICESUICONTAINERNAME — floci-ui — Name of the sidecar container
• FLOCISERVICESUIPORT — 4500 — Host port the console is published on
• FLOCISERVICESUIBINDADDRESS — (none) — Host interface that port is published on. Unset publishes on every interface; set 127.0.0.1 when Floci's own port is loopback-only
• FLOCISERVICESUIKEEPRUNNINGONSHUTDOWN — false — Leave the sidecar running when Floci stops

概述

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

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.

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.

The old hectorvent/floci repository no longer receives updates.