floci-az puts an Azure-shaped API on localhost:4577

One endpoint, and the rest of the family around it

Floci AZ is a free, open-source local Azure emulator for development, testing and CI. It gives you Azure-compatible services on your machine without requiring a cloud account, an auth token, or paid feature gates, and the README's instruction is simple: point your Azure SDK, CLI or Terraform at http://localhost:4577 and keep your existing workflows.

That last clause is the design goal. A local emulator is only useful if the code under test does not have to change, so the emulator's job is to accept the request shape your client library already produces and to answer in a way the client already understands.

The project is the Azure member of the Floci emulator family, and the README puts the siblings in a table with their ports: floci for AWS on 4566, floci-az for Azure on 4577, floci-gcp for GCP on 4588 and floci-oci for OCI on 4599. The AI context block in the README is explicit that Floci AZ is the Azure equivalent of Floci and is NOT LocalStack, which tells you the project is positioning itself against the general purpose cloud emulator rather than as a drop-in replacement for one.

The implementation is Java on Quarkus, with the repository holding a src directory, an azfloci module, a pom.xml and a Maven wrapper, plus a compatibility-tests directory, a docker directory, an overrides directory and an mkdocs.yml for the documentation.

The licence is MIT, the homepage is floci.io/floci-az, the last push was on 2026-10-22, and the recent releases are 0.13.0 on 2026-09-15, 0.14.0 on 2026-10-06 and 0.15.0 on 2026-10-15.

The service list, and the sidecars that make some of it real

The surface area is large, and the README's AI context block enumerates it: Azure Storage with Blob, Queue and Table, Azure Functions, App Configuration, Key Vault, Event Hubs, Service Bus under Microsoft.ServiceBus, Cosmos DB, Azure SQL Database, Azure Database for PostgreSQL, MySQL and MariaDB, AKS, Container Apps, API Management, Virtual Network, Virtual Machines, Azure Cache for Redis, Container Registry, Container Instances, Event Grid, Azure Monitor and Log Analytics, Communication Services Email, Managed Identity with an IMDS token endpoint, Azure Policy with policy, set definitions, assignments and exemptions, and Microsoft Entra ID with OpenID Connect and OAuth2 token issuance including interactive auth-code plus PKCE sign-in, plus a narrow Microsoft Graph slice for service principal discovery and group membership.

That is a lot, and a feature list this long is where the next section of the README matters. The note on real Docker where fidelity matters says Azure Functions, Event Hubs, and the Cosmos DB engine APIs for MongoDB, PostgreSQL, Cassandra and Gremlin use real Docker-backed execution instead of shallow mocks.

The tech stack line explains how. Docker-in-Docker backs Azure Functions, an Artemis sidecar carries Event Hubs over AMQP, a Redpanda sidecar provides Kafka for Event Hubs as an opt-in on port 9093, a k3s sidecar provides the AKS API on ports 6443 to 7443, and a Redis sidecar backs Azure Cache for Redis on ports 6379 to 6399.

So the emulator is a mix of two strategies. Some services are implemented in the Quarkus process itself, and the ones where a mock would be obviously wrong are delegated to real engines running beside it. That hybrid is the honest answer to a question like Cosmos DB with four different database engines behind it.

The port map is in the same block, and it is worth keeping: HTTP on 4577, AMQP on 5672 for Event Hubs, Kafka on 9093 as opt-in, the k3s API on 6443 to 7443, and Redis on 6379 to 6399.

Two ways to start it, and no credentials to manage

The quick start is a compose file and one command.

# docker-compose.yml
services:
  floci-az:
    image: floci/floci-az:latest
    ports:
      - "4577:4577"
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock  # required for Azure Functions

docker compose up

Or the same thing with a plain docker run:

docker run -d --name floci-az \
  -p 4577:4577 \
  -v /var/run/docker.sock:/var/run/docker.sock \
  floci/floci-az:latest

The credential story is the last piece and it is the most unusual part of the design. All services are available at http://localhost:4577, and you can use any account name and key, because SharedKey credentials are not validated. There is no account to create, no token to refresh and no feature gate to trip, which is the whole reason the project exists as a separate member of the Floci family rather than a configuration of something else.

The Docker socket mount is required for Azure Functions, because the emulator spawns runtime containers on demand. The README says explicitly that if you do not use Functions, the socket mount is optional.

That optionality is worth pausing on. Mounting /var/run/docker.sock into a container gives that container effective control of the host's Docker daemon, which is a well known way for a container escape to become a host compromise. It is the standard trick for local emulator and CI setups, and it is also the kind of thing that a security review will ask about. The README tells you it is optional when you do not need Functions, and that is the mitigation.

TLS on the same port, and the two clients that demand it

TLS is optional and off by default, but two common clients refuse to work without it, and the README explains both.

The first is the Azure Cosmos DB Java SDK, which enforces TLS in gateway mode. The fix is a built-in TLS proxy that serves HTTP and HTTPS on the same port:

# docker-compose.yml
services:
  floci-az:
    image: floci/floci-az:latest
    ports:
      - "4577:4577"
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
      - ./data:/app/data        # persist generated cert across restarts
    environment:
      FLOCI_AZ_TLS_ENABLED: "true"
      FLOCI_AZ_HOSTNAME: floci-az   # add Docker service name to cert SANs

The certificate is generated at startup by the emulator itself, using BouncyCastle, and cached under data/tls/. You fetch it at runtime from GET http://localhost:4577/_floci/tls-cert and install it into your truststore, so there is no static certificate to bundle or import manually. The environment block is the AI context in the README: set FLOCI_AZ_TLS_ENABLED=true, and the self-signed certificate is served at that endpoint for dynamic truststore installation.

The second client is Terraform or OpenTofu with the azurerm provider, which discovers the cloud over HTTPS with GET https://<host>/metadata/endpoints and therefore fails against plain HTTP. The README links a separate Terraform and OpenTofu guide for that case.

The mechanism is a protocol-sniffing proxy, so a client that speaks TLS gets TLS and one that speaks plain HTTP gets plain HTTP on the same port. That is why the Cosmos DB SDK and the azurerm provider can share an endpoint with everything else rather than needing a second port.

Compatibility is tested across five languages and two IaC tools

The repository devotes a whole directory to proving that the emulator matches what real clients expect, and that is the part of the project that determines whether it is usable.

The compatibility-tests directory holds a separate suite per client: sdk-test-python, sdk-test-java, sdk-test-node, sdk-test-dotnet, sdk-test-cpp, and compat-terraform and compat-opentofu for infrastructure as code, plus a compat-azcli directory for the Azure command line. The Makefile has a target for each of them, with local variants, and separate targets for the Cosmos DB engines, MongoDB, PostgreSQL, Cassandra, Gremlin, the table and NoSQL APIs, for SQL, MySQL and MariaDB, for Service Bus compatibility, for blob tests per language, and for the Terraform, OpenTofu and azcli paths.

There is also a smoke target for native crypto, a group of az-data targets for synchronising and checking data, and three targets named for cloud literals with check, audit and baseline variants, which look like a guard against the emulator drifting away from the real service's literal behaviour.

The compose file in the repository shows the development configuration those tests run against. Storage mode is set to memory through FLOCI_AZ_STORAGE_MODE, the sidecars are told which Docker network to use with FLOCI_AZ_SERVICES_DOCKER_NETWORK, TLS is switched on with FLOCI_AZ_TLS_ENABLED, and FLOCI_AZ_HOSTNAME sets the name that goes into the certificate subject alternative names. The compose file also defines a named bridge network, floci_az_default, with an alias so that the container is reachable by its service name.

For an adopter, the practical value of this is that the answer to whether a given SDK works against the emulator is not a guess. It is a target in the Makefile that someone runs on every change.

Where floci-az is the wrong tool

The limits follow from the strategy of emulating the API surface rather than the behaviour.

First, coverage is not fidelity. The service list is long, but inside each service the behaviour is a reimplementation, and a reimplementation is a set of choices. An emulator that is wrong in a corner case is worse than no emulator, because a test that passes locally tells you nothing about production. The compatibility tests raise confidence in the common paths; they do not make the emulator Azure.

Second, the hybrid sidecar design has consequences. Event Hubs, Cosmos DB engines, AKS and Redis need real engines running beside the emulator, which means the deployment is several containers rather than one, and the k3s sidecar for AKS is a Kubernetes cluster inside your test environment. That is a lot of machinery for a service you may only need one API of.

Third, the Docker socket. The emulator needs it for Functions, and mounting it means the emulator can start containers on the host with host privileges. On a developer machine that is a normal trade, and on a shared CI runner it is a decision that should be written down.

Fourth, this is a local development and testing tool, not a production system, and the README frames it that way. It has no account model, no auth token and no feature gates, and SharedKey credentials are not validated, which means it cannot be used to model an authorisation bug, and it should never be exposed on a network where an unvalidated write endpoint would be a problem.

Fifth, the rate of change is high. Three releases landed in the last month, and the emulator is chasing a cloud that ships continuously. The upstream constraint is Azure's own surface, and for a team that needs to run against the real thing, the emulator is a convenience rather than a replacement.

Editorial conclusion

Teams whose CI or local development needs Azure-shaped services without an Azure account should try floci-az, because the emulator accepts your existing SDK, CLI and Terraform configuration at a single endpoint and keeps real Docker-backed behaviour where a mock would be a lie. It is the wrong tool when your workflow depends on Azure behaviour the emulator approximates rather than implements, since the list of supported services is long but the fidelity inside each one is a project decision, and it is the wrong tool if you cannot accept a container that mounts the Docker socket. Before adopting, check the compatibility tests for your language and service, and read the TLS section, because the Azure Cosmos DB Java SDK and the azurerm provider both fail against plain HTTP.

Frequently asked questions

Official sources

1. floci-io/floci-az on GitHub
2. License: MIT
3. Project website
4. README
5. Releases