floci Documentation

Light, fluffy, and always free 
No account. No auth token. No feature gates. Just <code>docker compose up</code>.

<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>

---

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.

Floci is named after floccus, the cloud formation that looks like popcorn.

Quick Start

The fastest way to run Floci is with the official CLI

bash

floci start

Export the AWS environment variables:

bash

eval $(floci env)

Use your existing AWS tools normally:

bash

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 region works. 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:

yaml

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

Start Floci:

bash

docker compose up

Then configure your AWS environment manually:

bash

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:

yaml

Before

image: hectorvent/floci:latest
After

image: floci/floci:latest

The old hectorvent/floci repository no longer receives updates.

</details>

Features

<details open>
<summary>Local AWS without the cloud account</summary>

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

</details>

<details>
<summary>Real Docker where fidelity matters</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>Drop-in AWS compatibility</summary>

Point standard AWS clients at http://localhost:4566. Existing credentials, regions, SDKs, CLI commands, and IaC workflows stay familiar.

</details>

<details>
<summary>Fast enough for CI</summary>

The native image starts in milliseconds and keeps idle memory low, making it practical for local development and test pipelines.

</details>

<details>
<summary>Configurable persistence</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.

| Capability | Floci | LocalStack Community |
|---|:---:|:---:|
| Auth token required | No | Yes |
| 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 | Yes | No |
| Cognito | Yes | No |
| RDS, ElastiCache, MSK | Real Docker | No |
| Neptune (graph DB + Gremlin WebSocket) | Real Docker | No |
| DocumentDB (MongoDB-compatible) | Real Docker | No |
| ECS, EC2, EKS | Real Docker | No |
| CodeBuild | Real Docker execution | No |
| Native binary | ~40 MB | No |

69 AWS services. Broad coverage. Free forever.

Architecture Overview

mermaid

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 · Bedrock Runtime · 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.

| Category | Services |
|---|---|
| Core app services | S3, SQS, SNS, DynamoDB, Lambda, IAM, KMS, Secrets Manager, SSM |
| Events and workflows | EventBridge, EventBridge Pipes, EventBridge Scheduler, Step Functions, CloudWatch Logs, CloudWatch Metrics |
| API and identity | API Gateway REST, API Gateway v2, AppSync, Cognito, ACM, Route53, Cloud Map |
| Containers and compute | ECS, EC2, Lightsail, EKS, MWAA, ECR, CodeBuild, CodeDeploy, CodePipeline, AWS Batch, Auto Scaling, Application Auto Scaling, Elastic Beanstalk, ELB v2 |
| Data, analytics, and AI | Athena, Glue, EMR, Firehose, Managed Service for Apache Flink, OpenSearch, S3 Vectors, Textract, Transcribe, Bedrock Runtime |
| Databases and caching | RDS, RDS Data API, Neptune, DocumentDB, MemoryDB, ElastiCache |
| Messaging and transfer | SES, Kinesis, MSK, Amazon MQ, Transfer Family, IoT Core |
| Security and governance | WAF v2, CloudTrail, CloudFront, Resource Groups Tagging API |
| Cost and billing | Pricing, Cost Explorer, Cost and Usage Reports, BCM Data Exports |
| Backup and config | AWS Backup, AWS Config, AppConfig, AppConfigData, CloudFormation, Cloud Control API |

For operation-level compatibility, see the Services Overview.

<details>
<summary>Detailed service notes</summary>

| Service | How it works | Notable features |
|---|---|---|
| SSM | In-process + EC2 containers | Parameter Store (version history, labels, SecureString, tagging); Run Command (SendCommand, GetCommandInvocation, direct EC2 container execution, agent polling) |
| SQS | In-process | Standard and FIFO queues, DLQ, visibility timeout, batch operations, tagging |
| SNS | In-process | Topics, subscriptions, SQS, Lambda and HTTP delivery, tagging |
| S3 | In-process | Versioning, multipart upload, pre-signed URLs, Object Lock, event notifications |
| S3 Vectors | In-process | Vector buckets, indexes, put / get / list / delete vectors, cosine similarity queries |
| DynamoDB | In-process | GSI, LSI, Query, Scan, TTL, transactions, batch operations; Streams with shard iterators and Lambda event source mapping |
| Lambda | Real Docker | Runtime environment, execution model, warm container pool, aliases, Function URLs |
| API Gateway REST | In-process | Resources, methods, stages, Lambda proxy, MOCK integrations, AWS integrations |
| API Gateway v2 | In-process | HTTP APIs, routes, integrations, JWT authorizers, stages |
| AppSync | In-process | GraphQL API management API, schema registry, AWS scalars, domain names, channel namespaces |
| IAM | In-process | Users, roles, groups, policies, instance profiles, access keys; STS AssumeRole, WebIdentity, SAML, GetFederationToken, GetSessionToken |
| Cognito | In-process | User pools, app clients, auth flows, JWKS and OpenID well-known endpoints |
| KMS | In-process | Encrypt, decrypt, sign, verify, data keys, aliases |
| Kinesis | In-process | Streams, shards, enhanced fan-out, split and merge |
| Secrets Manager | In-process | Versioning, resource policies, tagging |
| Step Functions | In-process | ASL execution, task tokens, execution history |
| CloudFormation | In-process | Stacks, change sets, resource provisioning, StackSets (cross-account instances) |
| EventBridge | In-process | Custom buses, rules, SQS, SNS and Lambda targets |
| EventBridge Pipes | In-process | Poller-based integration connecting SQS, Kinesis, DynamoDB, and MSK sources to targets with optional filtering |
| EventBridge Scheduler | In-process | Schedule groups, schedules, flexible time windows, retry policies, DLQs |
| CloudWatch Logs | In-process | Log groups, streams, ingestion, filtering |
| CloudWatch Metrics | In-process | Custom metrics, statistics, alarms |
| ElastiCache | Real Docker | Redis / Valkey protocol, IAM auth, SigV4 validation |
| MemoryDB | Real Docker | Redis / Valkey protocol via real containers; JSON 1.1 control plane; reuses ElastiCache RESP proxy |
| RDS | Real Docker | PostgreSQL, MySQL, MariaDB, IAM auth, JDBC-compatible engines |
| RDS Data API | REST JSON over real RDS containers | Raw SQL execution and transactions for local MySQL / MariaDB RDS resources |
| Neptune | Real Docker | Graph DB via TinkerPop Gremlin Server (default) or Neo4j for openCypher/Bolt (NEPTUNE_DB_TYPE); RDS-shaped control plane; SigV4 proxy on port 8182 |
| DocumentDB | Real Docker, mock mode available | MongoDB-compatible cluster via real MongoDB containers; RDS-shaped control plane; MongoDB wire protocol on port 27017 |
| MSK | Real Docker | Kafka-compatible broker via Redpanda |
| Amazon MQ | Real Docker | RabbitMQ broker via rabbitmq:3-management; AMQP + management console |
| Athena | In-process with DuckDB sidecar | Real SQL execution over S3 and Glue-backed views |
| Glue | In-process | Data Catalog, Schema Registry, tables consumed by Athena |
| EMR | In-process | Cluster (job flow) lifecycle, instance groups and fleets, steps, security configurations, tagging |
| Data Firehose | In-process | Streaming delivery, NDJSON flush to S3 |
| Managed Service for Apache Flink | Real Docker | Kinesis Analytics V2 control plane; StartApplication runs a real Flink cluster (JobManager + TaskManager, image per RuntimeEnvironment), pulls the application JAR from local S3, and submits the job |
| ECS | Real Docker | Clusters, task definitions, tasks, services, capacity providers, task sets |
| EC2 | Real Docker | RunInstances launches containers, SSH key injection, UserData, IMDS, VPC resources |
| Lightsail | In-process | Instances, disks, static IPs, key pairs, ports, tags, regions, blueprints, bundles, operations |
| ACM | In-process | Certificate issuance and validation lifecycle |
| ECR | In-process with real registry | Repositories, docker push / pull, image-backed Lambda functions |
| Resource Groups Tagging API | In-process | GetResources, tag and untag resources, tag key and value discovery across services |
| SES | In-process | v1 and v2 APIs: send email, raw email, identity verification, DKIM, templates, configuration sets, account sending |
| OpenSearch | Real Docker | Domain CRUD, tags, versions, instance types, upgrade stubs |
| AppConfig | In-process | Applications, environments, profiles, hosted versions, deployments |
| AppConfigData | In-process | Configuration sessions and dynamic configuration retrieval |
| Bedrock Runtime | In-process stub | Dummy Converse and InvokeModel responses for local development |
| EKS | Real Docker, mock mode available | k3s clusters with live Kubernetes API server |
| MWAA | Real Docker, mock mode available | Real Apache Airflow (LocalExecutor) + Postgres metadata DB per environment; web/CLI proxy; S3-backed DAG sync |
| ELB v2 | In-process | ALB, NLB, target groups, listeners, routing rules, Lambda targets, tags |
| CodeBuild | In-process with real Docker | Real buildspec execution, CloudWatch logs, S3 artifacts |
| CodeDeploy | In-process with Lambda traffic shifting | Deployment groups, configs, lifecycle hooks, auto-rollback |
| CodePipeline | In-process orchestration | Pipelines, executions, S3 artifacts, approvals, local providers, custom workers |
| AWS Batch | In-process | Compute environments, job queues, job definitions, job submission and lifecycle |
| Auto Scaling | In-process with reconciler | Launch configs, ASGs, desired capacity reconciliation, lifecycle hooks |
| Application Auto Scaling | In-process | Scalable targets, target-tracking and step scaling policies, CloudWatch alarm creation, tagging (policies are stored but inert) |
| Elastic Beanstalk | In-process | Applications, application versions, environments, configuration templates, platform and solution stack metadata |
| AWS Backup | In-process | Vaults, backup plans, selections, simulated job lifecycle, recovery points |
| AWS Config | In-process | Config rules, configuration recorders, delivery channels, conformance packs, tagging |
| CloudTrail | In-process | Trails, event selectors (S3 data events with bucket/prefix matching), StartLogging/StopLogging, scheduled gzipped log file emission to the destination bucket at AWS-shaped key paths, IAM-deny path emits AccessDenied records |
| CloudFront | In-process | Distributions, origins, cache behaviors, invalidations, tagging |
| WAF v2 | In-process | Web ACLs, IP sets, regex pattern sets, rule groups, logging configs, resource associations, tagging (REGIONAL and CLOUDFRONT scopes) |
| Route53 | In-process | Hosted zones, SOA and NS records, resource record sets, change tracking, tagging |
| Cloud Map | In-process | HTTP and DNS namespaces, services, instance registration, discovery queries, operations, tagging |
| Transfer Family | In-process | Server lifecycle, user management, SSH key import, tagging |
| Textract | In-process stub | API-compatible stubs, dummy block data, async job simulation |
| Transcribe | In-process stub | Transcription jobs and custom vocabularies; jobs complete immediately, no real audio processing |
| Pricing | In-process with static snapshot | Product discovery, attributes, price list files, pagination |
| Cost Explorer | In-process | Cost synthesized from Floci resource state and pricing snapshots |
| Cost and Usage Reports | In-process with floci-duck sidecar | CUR 2.0 and FOCUS 1.2 columns, account-scoped storage, Parquet emission |
| BCM Data Exports | In-process | Export lifecycle, executions, update and delete operations |

</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.

| Service | Default image | What is real |
|---|---|---|
| Lambda | public.ecr.aws/lambda/<runtime> | 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 |
| Managed Service for Apache Flink | apache/flink:<version> | Apache Flink JobManager; image chosen per RuntimeEnvironment (FLINK-1_15 … FLINK-1_20, FLINK-2_0 … FLINK-2_3) |
| 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 |
| MWAA | apache/airflow:<version>-python3.12 + postgres:16-alpine | Real Apache Airflow (LocalExecutor: scheduler + webserver) with its own Postgres metadata DB; webserver/CLI reachable via Floci's proxy |
| 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_KINESIS_ANALYTICS_DEFAULT_IMAGE | _(unset; chosen per RuntimeEnvironment)_ |
| 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_MWAA_DEFAULT_POSTGRES_IMAGE | postgres:16-alpine |
| 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.

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.

SDK Integration

Point your existing AWS SDK at http://localhost:4566.

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());

</details>

<details>
<summary>Python, boto3</summary>

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"])

</details>

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",
  }),
);

</details>

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)
}

</details>

rust

use aws_sdk_secretsmanager::config::{Credentials, Region};
use aws_sdk_secretsmanager::Client;
#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    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(())
}

</details>

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

</details>

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 | GitHub |
| Node.js | @floci/testcontainers | 0.1.0 | npm | GitHub |
| Python | testcontainers-floci | 0.1.1 | PyPI | GitHub |
| Go | In progress | In progress | N/A | GitHub |

xml

<dependency>
    <groupId>io.floci</groupId>
    <artifactId>testcontainers-floci</artifactId>
    <version>1.4.0</version>
    <scope>test</scope>
</dependency>

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.

</details>

<details>
<summary>Node.js / TypeScript</summary>

npm install --save-dev @floci/testcontainers

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" }));
  });
});

</details>

<details>
<summary>Python</summary>

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")

</details>

Compatibility Testing

The 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.

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

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 or GitHub Discussions. Feature ideas, compatibility questions, design tradeoffs, and rough proposals are welcome.

Star History

Contributors

License

MIT. Use it however you want.

floci

What is Floci?

Quick Start

Watch it run

Before

After

Features

Why Floci?

Architecture Overview

Supported Services

Real Docker Integration

Overriding default images

Persistence and Storage Modes

Multi-Account Isolation

SDK Integration

Testcontainers

Compatibility Testing

Migrating from LocalStack

Before

After, standard image

After, if init scripts need AWS CLI or boto3

Image Tags

Recommended

Includes AWS CLI and boto3

Pinned release

Track main

Configuration

Multi-container Docker Compose

Community

Sponsors

🥇 Gold

🥈 Silver

🥉 Community

Star History

Contributors

License

What is Floci? Copy Chapter

Quick Start Copy Chapter

Watch it run Copy Section

Before

After

Features Copy Chapter

Why Floci? Copy Chapter

Architecture Overview Copy Chapter

Supported Services Copy Chapter

Real Docker Integration Copy Chapter

Overriding default images Copy Section

Persistence and Storage Modes Copy Chapter

Multi-Account Isolation Copy Chapter

SDK Integration Copy Chapter

Testcontainers Copy Chapter

Compatibility Testing Copy Chapter

Migrating from LocalStack Copy Chapter

Before

After, standard image

After, if init scripts need AWS CLI or boto3

Image Tags Copy Chapter

Recommended

Includes AWS CLI and boto3

Pinned release

Track main

Configuration Copy Chapter

Multi-container Docker Compose Copy Section

Community Copy Chapter

Sponsors Copy Chapter

🥇 Gold Copy Section

🥈 Silver Copy Section

🥉 Community Copy Section

Star History Copy Chapter

Contributors Copy Chapter

License Copy Chapter

What is Floci?

Quick Start

Watch it run

Features

Why Floci?

Architecture Overview

Supported Services

Real Docker Integration

Overriding default images

Persistence and Storage Modes

Multi-Account Isolation

SDK Integration

Testcontainers

Compatibility Testing

Migrating from LocalStack

Image Tags

Configuration

Multi-container Docker Compose

Community

Sponsors

🥇 Gold

🥈 Silver

🥉 Community

Star History

Contributors

License