Floci
Light, fluffy, and always free - AWS Local Emulator
Install / Use
/learn @hectorvent/FlociREADME
LocalStack's community edition sunset in March 2026 — requiring auth tokens, and freezing security updates. Floci is the no-strings-attached alternative.
Why Floci?
| | Floci | LocalStack Community | |---|---|---| | Auth token required | No | Yes (since March 2026) | | Security updates | Yes | Frozen | | Startup time | ~24 ms | ~3.3 s | | Idle memory | ~13 MiB | ~143 MiB | | Docker image size | ~90 MB | ~1.0 GB | | License | MIT | Restricted | | API Gateway v2 / HTTP API | ✅ | ❌ | | Cognito | ✅ | ❌ | | ElastiCache (Redis + IAM auth) | ✅ | ❌ | | RDS (PostgreSQL + MySQL + IAM auth) | ✅ | ❌ | | S3 Object Lock (COMPLIANCE / GOVERNANCE) | ✅ | ⚠️ Partial | | DynamoDB Streams | ✅ | ⚠️ Partial | | IAM (users, roles, policies, groups) | ✅ | ⚠️ Partial | | STS (all 7 operations) | ✅ | ⚠️ Partial | | Kinesis (streams, shards, fan-out) | ✅ | ⚠️ Partial | | KMS (sign, verify, re-encrypt) | ✅ | ⚠️ Partial | | Native binary | ✅ ~40 MB | ❌ |
21+ services. 408/408 SDK tests passing. Free forever.
Quick Start
# docker-compose.yml
services:
floci:
image: hectorvent/floci:latest
ports:
- "4566:4566"
volumes:
- ./data:/app/data
docker compose up
All services are available at http://localhost:4566. Use any AWS region — credentials can be anything.
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
# Try it
aws s3 mb s3://my-bucket
aws sqs create-queue --queue-name my-queue
aws dynamodb list-tables
SDK Integration
Point your existing AWS SDK at http://localhost:4566 — no other changes needed.
// Java (AWS SDK v2)
DynamoDbClient client = DynamoDbClient.builder()
.endpointOverride(URI.create("http://localhost:4566"))
.region(Region.US_EAST_1)
.credentialsProvider(StaticCredentialsProvider.create(
AwsBasicCredentials.create("test", "test")))
.build();
# Python (boto3)
import boto3
client = boto3.client("s3",
endpoint_url="http://localhost:4566",
region_name="us-east-1",
aws_access_key_id="test",
aws_secret_access_key="test")
// Node.js (AWS SDK v3)
import { S3Client } from "@aws-sdk/client-s3";
const client = new S3Client({
endpoint: "http://localhost:4566",
region: "us-east-1",
credentials: { accessKeyId: "test", secretAccessKey: "test" },
forcePathStyle: true,
});
Compatibility Testing
For full compatibility validation against real SDK and client workflows, use floci-compatibility-tests.
This companion project provides a dedicated compatibility test suite for Floci across multiple SDKs and tooling scenarios, and is the recommended starting point when verifying integration behavior end to end.
Available SDK test modules:
| Module | Language / Tool | SDK / Client |
|---|---|---|
| sdk-test-java | Java 17 | AWS SDK for Java v2 |
| sdk-test-go | Go | AWS SDK for Go v2 |
| sdk-test-node | Node.js | AWS SDK for JavaScript v3 |
| sdk-test-python | Python 3 | boto3 |
| sdk-test-rust | Rust | AWS SDK for Rust |
| sdk-test-awscli | Bash | AWS CLI v2 |
The repository also includes compatibility validation for infrastructure tooling through compat-cdk (AWS CDK v2) and compat-opentofu (OpenTofu / Terraform-compatible workflows).
Image Tags
| Tag | Description |
|---|---|
| latest | Native image — sub-second startup (recommended) |
| latest-jvm | JVM image — broadest platform compatibility |
| x.y.z / x.y.z-jvm | Pinned releases |
Configuration
All settings are overridable via environment variables (FLOCI_ prefix).
| Variable | Default | Description |
|---|---|---|
| QUARKUS_HTTP_PORT | 4566 | HTTP port |
| FLOCI_DEFAULT_REGION | us-east-1 | Default AWS region |
| FLOCI_DEFAULT_ACCOUNT_ID | 000000000000 | Default AWS account ID |
| FLOCI_BASE_URL | http://localhost:4566 | Base URL used in API responses (e.g. SQS QueueUrl) |
| FLOCI_HOSTNAME | (unset) | Override hostname in response URLs (for Docker Compose) |
| FLOCI_STORAGE_MODE | hybrid | memory · persistent · hybrid · wal |
| FLOCI_STORAGE_PERSISTENT_PATH | ./data | Data directory |
→ Full reference: configuration docs → Per-service storage overrides: storage docs
Multi-container Docker Compose: When your application runs in a separate container from Floci, set FLOCI_HOSTNAME to the Floci service name so that returned URLs (e.g. SQS QueueUrl) resolve correctly:
services:
floci:
image: hectorvent/floci:latest
ports:
- "4566:4566"
environment:
- FLOCI_HOSTNAME=floci # URLs will use http://floci:4566/...
my-app:
environment:
- AWS_ENDPOINT_URL=http://floci:4566
depends_on:
- floci
Without this, SQS returns http://localhost:4566/... in QueueUrl responses, which resolves to the wrong container.
License
MIT — use it however you want.
