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

` | AWS runtime environment, execution model, warm container pool | | ElastiCache | `valkey/valkey:8` | Redis / Valkey protocol, ACL-based IAM auth, SigV4 validation | | RDS PostgreSQL | `postgres:16-alpine` | PostgreSQL engine, IAM auth, JDBC-compatible access | | RDS MySQL / Aurora | `mysql:8.0` | MySQL engine, IAM auth, JDBC-compatible access | | RDS MariaDB | `mariadb:11` | MariaDB engine, IAM auth, JDBC-compatible access | | Neptune | `tinkerpop/gremlin-server:3.7.3` | TinkerPop Gremlin Server; Gremlin WebSocket on port 8182; SigV4 auth proxy | | Neptune (openCypher) | `neo4j:5-community` | Neo4j backend when `FLOCI_SERVICES_NEPTUNE_DB_TYPE=neo4j`; openCypher over Bolt | | DocumentDB | `mongo:7.0` | MongoDB engine; MongoDB wire protocol on port 27017 | | MSK | `redpandadata/redpanda:latest` | Kafka-compatible broker via Redpanda | | Amazon MQ | `rabbitmq:3-management` | RabbitMQ broker; AMQP on port 5672, management console on 15672 | | EC2 | AMI-mapped Linux images | Linux containers, SSH key injection, UserData, IMDS, IAM credentials | | ECS | User-specified task image | Container lifecycle, start, stop, health checks | | EKS | `rancher/k3s:latest` | Kubernetes API server via k3s | | CodeBuild | User-specified environment image | Buildspec execution, log streaming, S3 artifact upload | | OpenSearch | `opensearchproject/opensearch:2` | Full OpenSearch engine with REST API | | ECR | `registry:2` | OCI-compatible registry for docker push and docker pull | Docker-backed services require the Docker socket: ```bash 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 | Variable | Default | |---|---| | `FLOCI_SERVICES_ELASTICACHE_DEFAULT_IMAGE` | `valkey/valkey:8` | | `FLOCI_SERVICES_RDS_DEFAULT_POSTGRES_IMAGE` | `postgres:16-alpine` | | `FLOCI_SERVICES_RDS_DEFAULT_MYSQL_IMAGE` | `mysql:8.0` | | `FLOCI_SERVICES_RDS_DEFAULT_MARIADB_IMAGE` | `mariadb:11` | | `FLOCI_SERVICES_MSK_DEFAULT_IMAGE` | `redpandadata/redpanda:latest` | | `FLOCI_SERVICES_OPENSEARCH_DEFAULT_IMAGE` | `opensearchproject/opensearch:2` | | `FLOCI_SERVICES_NEPTUNE_DEFAULT_IMAGE` | `tinkerpop/gremlin-server:3.7.3` | | `FLOCI_SERVICES_NEPTUNE_DEFAULT_NEO4J_IMAGE` | `neo4j:5-community` | | `FLOCI_SERVICES_DOCDB_DEFAULT_IMAGE` | `mongo:7.0` | | `FLOCI_SERVICES_EKS_DEFAULT_IMAGE` | `rancher/k3s:latest` | | `FLOCI_SERVICES_ECR_REGISTRY_IMAGE` | `registry:2` | | `FLOCI_ECR_BASE_URI` | `public.ecr.aws` | ## 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. | Mode | Behavior | Best for | Durability | |---|---|---|:---:| | `memory` | Entirely in RAM. Data is lost when the container stops. | CI and ephemeral tests | None | | `persistent` | Loaded at startup and flushed to disk immediately on every write operation. | Simple local state preservation with immediate persistence | Medium | | `hybrid` | In-memory performance with periodic async flushing every 5 seconds. | Local development | Good | | `wal` | Write-ahead log. Every mutation is logged before responding. | Maximum durability | Highest | 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](https://floci.io/floci/configuration/storage/). ## 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. ```bash 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](https://floci.io/floci/configuration/multi-account/). ## SDK Integration Point your existing AWS SDK at `http://localhost:4566`.

Java, AWS SDK v2

```java var client = DynamoDbClient.builder() .endpointOverride(URI.create("http://localhost:4566")) .region(Region.US_EAST_1) .credentialsProvider(StaticCredentialsProvider.create( AwsBasicCredentials.create("test", "test"))) .build(); client.createTable(b -> b .tableName("demo-table") .billingMode(BillingMode.PAY_PER_REQUEST) .attributeDefinitions( AttributeDefinition.builder().attributeName("pk").attributeType(ScalarAttributeType.S).build()) .keySchema( KeySchemaElement.builder().attributeName("pk").keyType(KeyType.HASH).build())); System.out.println(client.listTables().tableNames()); ```

Python, boto3

```python import boto3 client = boto3.client( "ssm", endpoint_url="http://localhost:4566", region_name="us-east-1", aws_access_key_id="test", aws_secret_access_key="test", ) client.put_parameter( Name="/demo/app/message", Value="hello from floci", Type="String", Overwrite=True, ) response = client.get_parameter(Name="/demo/app/message") print(response["Parameter"]["Value"]) ```

Node.js, AWS SDK v3

```javascript import { SQSClient, SendMessageCommand } from "@aws-sdk/client-sqs"; const client = new SQSClient({ endpoint: "http://localhost:4566", region: "us-east-1", credentials: { accessKeyId: "test", secretAccessKey: "test" }, }); await client.send( new SendMessageCommand({ QueueUrl: "http://localhost:4566/000000000000/demo-queue", MessageBody: "hello from floci", }), ); ```

Go, AWS SDK v2

```go package main import ( "context" "fmt" "log" "github.com/aws/aws-sdk-go-v2/config" "github.com/aws/aws-sdk-go-v2/credentials" "github.com/aws/aws-sdk-go-v2/service/s3" ) func main() { cfg, err := config.LoadDefaultConfig(context.TODO(), config.WithRegion("us-east-1"), config.WithCredentialsProvider( credentials.NewStaticCredentialsProvider("test", "test", ""), ), config.WithBaseEndpoint("http://localhost:4566"), ) if err != nil { log.Fatal(err) } client := s3.NewFromConfig(cfg, func(o *s3.Options) { o.UsePathStyle = true }) out, err := client.ListBuckets(context.TODO(), nil) if err != nil { log.Fatal(err) } fmt.Println(out.Buckets) } ```

Rust, AWS SDK

```rust use aws_sdk_secretsmanager::config::{Credentials, Region}; use aws_sdk_secretsmanager::Client; #[tokio::main] async fn main() -> Result<(), Box> { let config = aws_config::defaults(aws_config::BehaviorVersion::latest()) .region(Region::new("us-east-1")) .credentials_provider(Credentials::new("test", "test", None, None, "floci")) .endpoint_url("http://localhost:4566") .load() .await; let client = Client::new(&config); client .create_secret() .name("demo/secret") .secret_string("hello from floci") .send() .await?; Ok(()) } ```

Bash, AWS CLI

```bash export AWS_ACCESS_KEY_ID=test export AWS_SECRET_ACCESS_KEY=test export AWS_DEFAULT_REGION=us-east-1 aws --endpoint-url http://localhost:4566 s3 mb s3://my-bucket aws --endpoint-url http://localhost:4566 s3 ls ```

## Testcontainers Floci has Testcontainers modules for starting isolated Floci instances directly from tests. This avoids shared state, manual daemon setup, and port conflicts. | Language | Package | Latest | Registry | Source | |---|---|---|---|---| | Java | `io.floci:testcontainers-floci` | `1.4.0` | [Maven Central](https://mvnrepository.com/artifact/io.floci/testcontainers-floci) | [GitHub](https://github.com/floci-io/testcontainers-floci) | | Node.js | `@floci/testcontainers` | `0.1.0` | [npm](https://www.npmjs.com/package/@floci/testcontainers) | [GitHub](https://github.com/floci-io/testcontainers-floci-node) | | Python | `testcontainers-floci` | `0.1.1` | [PyPI](https://pypi.org/project/testcontainers-floci/) | [GitHub](https://github.com/floci-io/testcontainers-floci-python) | | Go | In progress | In progress | N/A | [GitHub](https://github.com/floci-io/testcontainers-floci-go) |

Java

```xml io.floci testcontainers-floci 1.4.0 test ``` ```java @Testcontainers class S3IntegrationTest { @Container static FlociContainer floci = new FlociContainer(); @Test void shouldCreateBucket() { S3Client s3 = S3Client.builder() .endpointOverride(URI.create(floci.getEndpoint())) .region(Region.of(floci.getRegion())) .credentialsProvider(StaticCredentialsProvider.create( AwsBasicCredentials.create(floci.getAccessKey(), floci.getSecretKey()))) .forcePathStyle(true) .build(); s3.createBucket(b -> b.bucket("my-bucket")); } } ``` For Testcontainers 2.x / Spring Boot 4.x, use version `2.5.0`.

Node.js / TypeScript

```sh npm install --save-dev @floci/testcontainers ``` ```ts import { FlociContainer } from "@floci/testcontainers"; import { S3Client, CreateBucketCommand } from "@aws-sdk/client-s3"; describe("S3", () => { let floci: FlociContainer; beforeAll(async () => { floci = await new FlociContainer().start(); }); afterAll(async () => { await floci.stop(); }); it("creates a bucket", async () => { const s3 = new S3Client({ endpoint: floci.getEndpoint(), region: floci.getRegion(), credentials: { accessKeyId: floci.getAccessKey(), secretAccessKey: floci.getSecretKey(), }, forcePathStyle: true, }); await s3.send(new CreateBucketCommand({ Bucket: "my-bucket" })); }); }); ```

Python

```sh pip install testcontainers-floci ``` ```python import boto3 from testcontainers_floci import FlociContainer def test_s3_create_bucket(): with FlociContainer() as floci: s3 = boto3.client( "s3", endpoint_url=floci.get_endpoint(), region_name=floci.get_region(), aws_access_key_id=floci.get_access_key(), aws_secret_access_key=floci.get_secret_key(), ) s3.create_bucket(Bucket="my-bucket") ```

## Compatibility Testing The [`compatibility-tests`](./compatibility-tests/) directory validates Floci across SDKs and tooling workflows. | Module | Language / Tool | SDK / Client | Tests | |---|---|---|---:| | `sdk-test-java` | Java 17 | AWS SDK for Java v2 | 1,326 | | `sdk-test-node` | Node.js | AWS SDK for JavaScript v3 | 449 | | `sdk-test-python` | Python 3 | boto3 | 311 | | `sdk-test-go` | Go | AWS SDK for Go v2 + RDS Data API SDK v1 | 157 | | `sdk-test-awscli` | Bash | AWS CLI v2 | 205 | | `compat-terraform` | Terraform | v1.10+ | 22 | | `compat-opentofu` | OpenTofu | v1.9+ | 16 | | `compat-cdk` | AWS CDK | v2+ | 20 | **2,506 automated compatibility tests across 5 SDKs and 3 IaC tools.** ## 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. ```yaml # Before image: localstack/localstack # After, standard image image: floci/floci:latest # After, if init scripts need AWS CLI or boto3 image: floci/floci:latest-compat ``` LocalStack environment variables are translated automatically: | LocalStack | Floci equivalent | |---|---| | `LOCALSTACK_HOST` | `FLOCI_HOSTNAME` | | `PERSISTENCE=1` | `FLOCI_STORAGE_MODE=persistent` | | `LAMBDA_DOCKER_NETWORK` | `FLOCI_SERVICES_LAMBDA_DOCKER_NETWORK` | | `LAMBDA_REMOVE_CONTAINERS=1` | `FLOCI_SERVICES_LAMBDA_EPHEMERAL=true` | | `DEBUG=1` | `QUARKUS_LOG_LEVEL=DEBUG` | 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 `LOCALSTACK_PARITY=false` to opt out of automatic translation. See the [full migration guide](https://floci.io/floci/getting-started/migrate-from-localstack/). ## Image Tags Every tag combines a variant and a channel. | Channel | Standard | Compat with AWS CLI and boto3 | |---|---|---| | Release, floating | `latest` | `latest-compat` | | Release, pinned | `x.y.z` | `x.y.z-compat` | | Nightly, floating | `nightly` | `nightly-compat` | | Nightly, dated | `nightly-mmddyyyy` | `nightly-mmddyyyy-compat` | Use `latest` for stable releases, a pinned version for reproducible builds, and `nightly` to track `main`. ```yaml # Recommended image: floci/floci:latest # Includes AWS CLI and boto3 image: floci/floci:latest-compat # Pinned release image: floci/floci:1.5.11 # Track main image: floci/floci:nightly ``` ## Configuration All settings are overridable through environment variables with the `FLOCI_` prefix. | Variable | Default | Description | |---|---|---| | `FLOCI_PORT` | `4566` | Port exposed by the Floci API | | `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 when Floci returns service URLs | | `FLOCI_HOSTNAME` | Unset | Hostname used in returned URLs when Floci runs inside Docker Compose | | `FLOCI_STORAGE_MODE` | `memory` | Storage mode: `memory`, `persistent`, `hybrid`, or `wal` | | `FLOCI_STORAGE_PERSISTENT_PATH` | `./data` | Directory used for persisted state | | `FLOCI_ECR_BASE_URI` | `public.ecr.aws` | ECR base URI used when pulling container images | | `FLOCI_SERVICES_S3_ENFORCE_AUTH` | `false` | Enforce S3 public/private read access and reject unknown signed S3 access keys | Full reference: [configuration docs](https://floci.io/floci/configuration/advanced/application-yml) ### Multi-container Docker Compose When your application runs in a different container, set `FLOCI_HOSTNAME` to the Floci service name so returned URLs, such as SQS `QueueUrl` values, resolve correctly. ```yaml services: floci: image: floci/floci:latest ports: - "4566:4566" environment: - FLOCI_HOSTNAME=floci my-app: environment: - AWS_ENDPOINT_URL=http://floci:4566 depends_on: - floci ``` Without this, services may return URLs using `localhost`, which points to the wrong container from the application container. ## Community Join the Floci community on [Slack](https://join.slack.com/t/floci/shared_invite/zt-3tjn02s3q-A00kEjJ1cZxsg_imTfy6Cw) or [GitHub Discussions](https://github.com/orgs/floci-io/discussions). Feature ideas, compatibility questions, design tradeoffs, and rough proposals are welcome. ## Sponsors Floci is independent open source, funded by its users. If Floci saves you time, consider [sponsoring the project](https://github.com/sponsors/floci-io) — every tier keeps the emulators fast, light, and free. ### 🥇 Gold Large logo with top placement, a dedicated support channel, input on roadmap priorities, and custom integration help. *Your logo here — [become a Gold sponsor](https://github.com/sponsors/floci-io).* ### 🥈 Silver Logo in this README and on floci.io, priority issue support, and a mention in release notes. *Your logo here — [become a Silver sponsor](https://github.com/sponsors/floci-io).* ### 🥉 Community Name in this README, a sponsor badge on GitHub, and our sincere thanks. - [Nexxion.ai](https://github.com/Nexxion-ai) - [Your name here](https://github.com/sponsors/floci-io) ## Star History

## Contributors ## License MIT. Use it however you want.