floci README

The project's README from github.com/floci-io/floci. As one markdown file: README.md.

Floci Floci

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

Latest Release Build Status Docker Pulls Docker Image Size License: MIT GitHub Stars

Quick Start · Features · Services · SDKs · Testcontainers · Migration · Docs

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.

Emulator Cloud Port
floci AWS 4566
floci-az Azure 4577
floci-gcp GCP 4588
floci-oci OCI 4599

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 region works. Credentials can be any non-empty values unless you explicitly enable stricter service-specific auth checks.

Prefer Docker Compose?

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
Using the old hectorvent/floci image?

Update your image name:

# Before
image: hectorvent/floci:latest

# After
image: floci/floci:latest

The old hectorvent/floci repository no longer receives updates.

Features

Local AWS without the cloud account

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

Real Docker where fidelity matters

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.

Drop-in AWS compatibility

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.

Fast enough for CI

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

Configurable persistence

Choose from in-memory, persistent, hybrid, and write-ahead log storage depending on the durability profile you need.

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

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.

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, SWF, CloudWatch Logs, CloudWatch Metrics, CloudWatch RUM, Managed Prometheus (AMP)
API and identity API Gateway REST, API Gateway v2, AppSync, Cognito, ACM, Route53, Route 53 Resolver, Cloud Map
Containers and compute ECS, EC2, Lightsail, EKS, MWAA, ECR, EFS, CodeBuild, CodeDeploy, CodePipeline, CodeGuru Reviewer, AWS Batch, Auto Scaling, Application Auto Scaling, Elastic Beanstalk, ELB v2, ELB Classic
Data, analytics, and AI Athena, Glue, Lake Formation, EMR, EMR Serverless, Redshift, Redshift Data API, Firehose, Managed Service for Apache Flink, OpenSearch, S3 Tables, S3 Vectors, Textract, Transcribe, Comprehend, Rekognition, Translate, Bedrock Runtime, Bedrock AgentCore
Databases and caching RDS, RDS Data API, Neptune, DocumentDB, MemoryDB, ElastiCache
Messaging and transfer SES, Kinesis, MSK, Amazon MQ, Transfer Family, IoT Core, Amazon Connect
Security and governance AWS Network Firewall, AWS RAM, Service Quotas, WAF v2, GuardDuty, Amazon Inspector, CloudTrail, CloudFront, Resource Groups Tagging API, Resource Explorer 2, CloudHSM v2, Organizations, AWS Account Management, IAM Access Analyzer, IAM Identity Center (SSO Admin), Identity Store, Amazon Macie, Amazon Detective, Security Hub, Control Catalog, Control Tower, Service Catalog
Cost and billing AWS Budgets, Pricing, Cost Explorer, Cost and Usage Reports, BCM Data Exports
Resilience, backup, and config AWS FIS, AWS Backup, AWS Config, AppConfig, AppConfigData, CloudFormation, Cloud Control API

For operation-level compatibility, see the Services Overview.

Detailed service notes
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
SWF In-process Decision and activity tasks, timers, child workflows, timeouts, real Lambda invocation
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, buffered flush to S3 with GZIP/ZIP/Snappy compression
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
Bedrock AgentCore In-process stub Stateful control plane (agent runtimes, gateways, memory, workload identity); canned InvokeAgentRuntime responses
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 Network Firewall In-process DescribeFirewall with stable emulated endpoint attachments for infrastructure tooling
Service Quotas In-process Generated quota catalog with generous static values; real quota codes for CodeBuild and Lambda concurrency
AWS RAM In-process EnableSharingWithAwsOrganization opt-in
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 FIS In-process All 26 management APIs for templates, experiments, target accounts, action and target discovery, safety lever, tagging, and pagination; experiment execution is a safe control-plane simulation and does not inject faults into other services
AWS Config In-process Config rules, evaluation-driven compliance (PutEvaluations, compliance details and summaries), configuration recorders, delivery channels, retention configuration, conformance packs, tagging
Organizations In-process Organizations, roots, nested OUs, member accounts, all policy types with FullAWSAccess and effective-policy inheritance, trusted service access, delegated administrators, resource policy, and the full invitation/handshake flow; created accounts are usable Floci accounts and member accounts can read the organization they belong to
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)
Resource Explorer 2 In-process All 32 management APIs: index and view lifecycle, multi-Region setup tasks, the full search query grammar, and tagging; 30 services expose their resources for search, gathered live rather than from an index
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

Real Docker Integration

Floci uses real Docker containers when in-process emulation would reduce f

floci (floci-io/floci)

Searching Database…

26.9K ·GitHub
Floci
这是什么？Floci 是一个免费开源的本地 AWS 模拟器：它在你自己的电脑上提供兼容 AWS 的 API——涵盖 S3、SQS、DynamoDB、Lambda、ECS 等众多服务——用于开发、测试和 CI，不需要云账号、认证令牌，也没有任何付费功能限制。
Floci 是我要导入的库，还是我要运行的服务？它是一个你运行的服务：一个 Docker 容器（或约 40 MB 的原生二进制文件），监听 4566 端口并支持 AWS API。你只需把现有的 AWS SDK、CLI、Terraform 或测试套件指向它即可——不会有任何东西被导入到你的代码里。
怎么把它跑起来？最快的方式：安装官方的 floci CLI，启动它，然后导出它打印出来的 AWS 环境变量。更喜欢直接用 Docker？把镜像加进 compose.yaml，运行 docker compose up，再手动配置 AWS 环境变量。
使用它需要 AWS 账号或认证令牌吗？不需要 AWS 账号，不需要认证令牌，也没有功能限制——任意非空的凭据都能用，除非你开启更严格的服务级认证检查。不过你需要装 Docker，它同时也是容器化服务的运行基础。
它真的覆盖所有 AWS 服务吗，还是有些只是模拟的？覆盖面很广——从 S3、SQS、DynamoDB 和 Lambda，到 ECS、EKS、RDS、Cognito 和 API Gateway v2，再到 Athena、EMR 和 Bedrock。大多数服务在进程内运行，少数服务（比如 Bedrock Runtime）只是返回假数据的桩实现。
它是给我自己的笔记本用的，还是也能用在 CI 流水线里？都可以——它同时面向本地开发和测试流水线。原生镜像约 24 毫秒启动，空闲时只占约 13 MiB 内存；Docker 镜像约 90 MB，所以每次测试运行时临时启动一个也完全可行。
它是真的免费吗，还是许可证里有坑？MIT 协议——任何用途都真正免费，包括商业用途。README 里还明确对比了 LocalStack 那种受限的许可证。
我调用 Lambda 函数或创建 RDS 数据库时，跑的是真东西吗？对保真度要求高的服务，是的：Lambda、RDS（PostgreSQL、MySQL、MariaDB）、Neptune、ElastiCache、MSK、ECS、EC2、EKS、OpenSearch 和 CodeBuild 都运行在真实的 Docker 容器里。而 S3、SQS 和 DynamoDB 这类较轻量的服务则是在进程内模拟的。
作者为什么不直接用 LocalStack，而要自己开发这个？LocalStack 的社区版在 2026 年 3 月停止维护，开始强制要求认证令牌，并冻结了安全更新。Floci 就是作为毫无附加条件的替代品而开发的：启动约 24 毫秒（对比约 3.3 秒），镜像约 90 MB（对比约 1 GB）。
我可以把 Terraform 指向它吗？可以——Terraform 通过标准的 HashiCorp AWS provider 在本地创建 AWS 形态的资源，Floci 甚至能为 Terraform state 提供一个模拟的 S3 后端。CDK 和 OpenTofu 的工作流也能用。
如果我重启容器，数据会全部丢失吗？不一定——存储方式是可配置的：你可以根据数据在多次运行之间需要多高的持久性，选择内存、持久化、混合或预写日志（write-ahead-log）模式。
What are similar projects?ministack, localstack, full-stack-data-engineering, forge, awesome-aws, infracost, encore, semaphore
Which topics is it in?ec2, ecs, terraform, infrastructure-as-code, emulator, s3, ci-cd, aws, containers, ci, testing, docker-compose
Creator
floci-io
Size
62.8 MB
Stars
26.9K
Updated
CommitOct 18Release2.3.0Oct 15
Age
7mo
Commits · 90 Days