The Azure Cosmos DB Java SDK enforces TLS in gateway mode. Enable the built-in TLS proxy to serve 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 self-signed certificate is generated at startup and cached under data/tls/. Fetch it at runtime from GET http://localhost:4577/_floci/tls-cert to install it into your truststore: no static cert to bundle or import manually.

Terraform / OpenTofu (azurerm) also requires TLS. The provider discovers the cloud over HTTPS (GET https://<host>/metadata/endpoints), so it fails against plain HTTP. See the Terraform / OpenTofu guide.

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

Azure Functions, Event Hubs, and Cosmos DB engine APIs (MongoDB, PostgreSQL, Cassandra, Gremlin) use real Docker-backed execution instead of shallow mocks.

Point standard Azure SDK clients at http://localhost:4577. Existing connection strings, credentials, and SDK workflows stay unchanged.

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

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

What is the Azure Cosmos DB Emulator?

The Azure Cosmos DB Emulator is Microsoft's official local emulator for Cosmos DB. It ships as a Windows installer or a Windows-container Docker image, exposes a built-in Data Explorer UI, and supports multiple Cosmos DB APIs (SQL, MongoDB, Cassandra, Gremlin, Table). It is a faithful replica of the cloud service, but it carries the full weight of that fidelity.

Head-to-head

Floci AZ does not aim to fully reproduce Azure Cosmos DB internals or cloud infrastructure behavior.

The goal is to provide high protocol and SDK compatibility through API-specific local engines optimized for:

• local development
• integration testing
• CI/CD pipelines
• lightweight developer environments

Each Cosmos API is backed by the engine that most closely matches its protocol and driver behavior.

Exact Azure features such as:

• RU/s throughput semantics
• global distribution
• multi-region replication
• autoscaling
• exact consistency guarantees
• Azure internal infrastructure behavior

are intentionally considered out of scope.

When to choose which

Use the official emulator when you need:

• Full fidelity with the Cosmos DB wire protocol and advanced features (stored procedures, triggers, change feed, TTL, RU/s governance, and multi-region topology simulation).
• The Data Explorer UI for manual data inspection.

Use Floci AZ when you need:

• A lightweight, cross-platform dev/test environment that starts in milliseconds.
• CI/CD pipelines on Linux runners (GitHub Actions, GitLab CI, CircleCI, etc.).
• Multiple Azure services in a single container: no juggling separate emulators.
• No TLS certificate headaches.
• Cosmos DB SQL API coverage is sufficient (CRUD, SQL queries, PATCH, transactional batch, pagination, aggregates, string functions).

Floci AZ includes an in-process API Management emulator intended for local development, SDK compatibility tests, and CI workflows that need APIM-shaped ARM resources plus a lightweight gateway. It is not a full Azure APIM gateway implementation.

APIM is available through:

• ARM-compatible resource paths under Microsoft.ApiManagement.
• Gateway routes under /{account}-apim/{serviceName}/{apiPath...}. With the default account this is http://localhost:4577/devstoreaccount1-apim/{serviceName}/....

Supported

• Management service resources: create, get, list, delete.
• API resources: create, get, list, delete.
• Operation resources: create, get, list, delete.
• Policy resources at service, API, and operation scope.
• Product resources and product-to-API links.
• Subscription resources with gateway subscription-key enforcement.
• Named values, including secret named values whose properties.value is not exposed in ARM responses.
• Backends and <set-backend-service backend-id="...">.
• OpenAPI JSON import for APIs, including operation generation from paths.
• OpenAPI reimport behavior that replaces previous generated operations.
• Gateway route matching for API paths and operation URL templates.
• Basic backend proxying when an API serviceUrl or backend policy is configured.

Supported Policy Subset

The policy engine intentionally supports a focused subset:

• <set-header> with exists-action="override", skip, append, and delete.
• <set-query-parameter> with exists-action="override", skip, and delete.
• <rewrite-uri template="...">.
• <set-backend-service base-url="...">.
• <set-backend-service backend-id="...">.
• <return-response>.
• <set-status code="..."> inside return-response.
• <set-body> inside return-response.
• Named value interpolation with {{name}} in supported policy values.

Partial or Out of Scope

The APIM emulator is intentionally scoped. These features are not fully emulated:

• The full APIM policy language and C# policy expressions.
• JWT validation, OAuth/OIDC flows, certificates, mTLS, and managed identities.
• API revisions, API versions, version sets, releases, tags, groups, users, loggers, diagnostics, named value Key Vault references, and developer portal behavior.
• APIM networking, private endpoints, custom domains, DNS, scale units, regions, SKU behavior, and deployment lifecycle timing.
• Exact APIM error formats, tracing, analytics, caching, rate-limit counters, quota counters, and distributed gateway behavior.

The current goal is practical local parity for common APIM provisioning and gateway tests, not full Azure infrastructure simulation.

# azure-storage-blob
from azure.storage.blob import BlobServiceClient

conn_str = (
    "DefaultEndpointsProtocol=http;AccountName=devstoreaccount1;"
    "AccountKey=Eby8vdM02xNOcqFlqUwJPLlmEtlCDXJ1OUzFT50uSRZ6IFsuFq2UVErCz4I6tq/K1SZFPTOtr/KBHBeksoGMGw==;"
    "BlobEndpoint=http://localhost:4577/devstoreaccount1;"
)

client = BlobServiceClient.from_connection_string(conn_str)
client.create_container("my-container")

blob = client.get_container_client("my-container").get_blob_client("hello.txt")
blob.upload_blob(b"Hello from floci-az!")
print(blob.download_blob().readall())

# azure-storage-queue
from azure.storage.queue import QueueServiceClient

conn_str = (
    "DefaultEndpointsProtocol=http;AccountName=devstoreaccount1;"
    "AccountKey=Eby8vdM02xNOcqFlqUwJPLlmEtlCDXJ1OUzFT50uSRZ6IFsuFq2UVErCz4I6tq/K1SZFPTOtr/KBHBeksoGMGw==;"
    "QueueEndpoint=http://localhost:4577/devstoreaccount1-queue;"
)

client = QueueServiceClient.from_connection_string(conn_str)
queue = client.create_queue("my-queue")
queue.send_message("Hello from floci-az!")
print(list(queue.receive_messages())[0].content)

# azure-data-tables
from azure.data.tables import TableServiceClient

conn_str = (
    "DefaultEndpointsProtocol=http;AccountName=devstoreaccount1;"
    "AccountKey=Eby8vdM02xNOcqFlqUwJPLlmEtlCDXJ1OUzFT50uSRZ6IFsuFq2UVErCz4I6tq/K1SZFPTOtr/KBHBeksoGMGw==;"
    "TableEndpoint=http://localhost:4577/devstoreaccount1-table;"
)

service = TableServiceClient.from_connection_string(conn_str)
table = service.create_table("MyTable")
table.create_entity({"PartitionKey": "pk1", "RowKey": "rk1", "Value": "hello"})
print(table.get_entity("pk1", "rk1")["Value"])

BlobServiceClient client = new BlobServiceClientBuilder()
    .connectionString(
        "DefaultEndpointsProtocol=http;AccountName=devstoreaccount1;" +
        "AccountKey=Eby8vdM02xNOcqFlqUwJPLlmEtlCDXJ1OUzFT50uSRZ6IFsuFq2UVErCz4I6tq/K1SZFPTOtr/KBHBeksoGMGw==;" +
        "BlobEndpoint=http://localhost:4577/devstoreaccount1;")
    .buildClient();

client.createBlobContainer("my-container");

BlobClient blob = client.getBlobContainerClient("my-container").getBlobClient("hello.txt");
blob.upload(new ByteArrayInputStream("Hello from floci-az!".getBytes()), 20);

import { BlobServiceClient } from "@azure/storage-blob";

const CONN =
  "DefaultEndpointsProtocol=http;AccountName=devstoreaccount1;" +
  "AccountKey=Eby8vdM02xNOcqFlqUwJPLlmEtlCDXJ1OUzFT50uSRZ6IFsuFq2UVErCz4I6tq/K1SZFPTOtr/KBHBeksoGMGw==;" +
  "BlobEndpoint=http://localhost:4577/devstoreaccount1;";

const client = BlobServiceClient.fromConnectionString(CONN);
const { containerClient } = await client.createContainer("my-container");

const blob = containerClient.getBlockBlobClient("hello.txt");
await blob.upload(Buffer.from("Hello from floci-az!"), 20);
console.log((await blob.downloadToBuffer()).toString());

Functions are managed via a REST management API and invoked over HTTP. The emulator spawns a real Azure Functions runtime container on first invoke and keeps it warm for subsequent calls.

BASE="http://localhost:4577/devstoreaccount1-functions"

# Create a function app
curl -s -X PUT "$BASE/admin/apps/my-app" \
  -H "Content-Type: application/json" \
  -d '{"runtime":"node","environment":{"MY_VAR":"hello"}}'

# Deploy a function (ZIP of your function code, base64-encoded)
ZIP_B64=$(base64 < my-function.zip)
curl -s -X PUT "$BASE/admin/apps/my-app/functions/hello" \
  -H "Content-Type: application/json" \
  -d "{\"handler\":\"index.handler\",\"timeoutSeconds\":60,\"zipBase64\":\"$ZIP_B64\"}"

# Invoke
curl "$BASE/api/my-app/hello?msg=world"

Supported runtimes: node, python, java, dotnet.

To select a Linux language version, pass the Azure-compatible linuxFxVersion. For example, Python 3.12 uses {"runtime":"python","linuxFxVersion":"Python|3.12"}.

azfloci is a companion CLI that acts as a transparent proxy for the official Azure CLI (az). It automatically injects the correct connection strings and disables SSL verification so you can use standard az commands against the local emulator.

# Optional: alias azfloci as az for a seamless experience
alias az='python3 /path/to/floci-az/azfloci/azfloci.py'

# Initialize or get connection string info
az setup

# Blob Storage
az storage container create --name my-container
az storage blob upload --container-name my-container --name hello.txt --file hello.txt
az storage blob list --container-name my-container --output table

# Queue Storage
az storage queue create --name my-queue
az storage message put --queue-name my-queue --content "Hello from CLI"

# Table Storage
az storage table create --name MyTable

azfloci automatically detects --account-name (defaulting to devstoreaccount1) and constructs the appropriate local endpoint.

Set the service name as the hostname so returned URLs resolve correctly inside Docker Compose:

services:
  floci-az:
    image: floci/floci-az:latest
    ports:
      - "4577:4577"
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
    networks:
      - app-net

  my-app:
    environment:
      AZURE_BLOB_ENDPOINT: http://floci-az:4577/devstoreaccount1
      AZURE_QUEUE_ENDPOINT: http://floci-az:4577/devstoreaccount1-queue
      AZURE_TABLE_ENDPOINT: http://floci-az:4577/devstoreaccount1-table
    depends_on:
      floci-az:
        condition: service_healthy
    networks:
      - app-net

networks:
  app-net:

Each engine's compatibility level is determined by how closely the underlying runtime matches what Azure Cosmos DB actually runs in production.

🟢 PostgreSQL API: very high parity

Azure Cosmos DB for PostgreSQL is Citus, a distributed PostgreSQL extension developed by the same team that runs inside Azure. The wire protocol, query language, and drivers are identical to vanilla PostgreSQL.

• Client SDK: standard PostgreSQL JDBC driver (org.postgresql:postgresql), the same driver you use in production, unchanged. Official quickstart.
• Engine: citusdata/citus Docker image (the exact same project).
• Known gaps: Azure-specific HA/scaling, multi-region replication, and Azure RBAC are infrastructure features with no local equivalent.
• Note: Microsoft is retiring this API. The recommended migration path is Azure Database for PostgreSQL (Elastic Clusters) or Cosmos DB for NoSQL.

🟢 MongoDB API: very high parity

Azure Cosmos DB for MongoDB exposes the full MongoDB wire protocol (BSON + OP_MSG). Connecting with any MongoDB driver targets the same binary framing and command set regardless of whether the server is a real mongod or the Azure Cosmos service.

• Client SDK: any MongoDB driver (mongodb-driver-sync, pymongo, mongodb Node.js package), and the connection string format is identical.
• Engine: mongo:7 Community Server, the reference implementation of the protocol.
• Known gaps: Azure-specific index types (wildcard compound), $lookup with let in some API versions, and RU/s throughput governance.

🟢 Table API: high parity

The Azure Table Storage REST API is a straightforward OData/JSON HTTP API. floci-az implements it directly in-process, with no Docker required. Because the protocol is pure HTTP with a well-documented spec, compatibility is structural: the same SDK targets the same URLs and receives the same JSON shapes.

• Client SDK: azure-data-tables SDK for Java, Python, Node.js, .NET. Use the official Cosmos DB for Table pattern: .endpoint() + AzureNamedKeyCredential. See Java quickstart. The connection string format is also supported for backward compatibility.
• Engine: in-memory (ConcurrentHashMap), instant startup, zero Docker overhead.
• Supported query operators: OData eq, ne, gt, ge, lt, le, and, or, not; $filter, $top, $select.
• Known gaps: Cosmos DB RU/s throughput model, TTL-based expiry, server-side pagination continuation tokens beyond $top.

🟢 Cassandra API: high parity

Azure Cosmos DB for Cassandra implements the Apache Cassandra CQL binary wire protocol (native transport, port 9042). Any CQL-compatible driver connects transparently. ScyllaDB is a CQL-compatible drop-in replacement that shares the same driver ecosystem.

• Client SDK: DataStax Java Driver (com.datastax.oss:java-driver-core), cassandra-driver-core, or any CQL v4 client. The contact point and port are all you need to change.
• Engine: scylladb/scylla (default) or any Apache Cassandra image via the image override.
• Known gaps: some Cosmos-specific TTL semantics, Cosmos RBAC, Cassandra LWT (lightweight transactions) edge cases, and ALLOW FILTERING query restrictions differ slightly.

🟡 Gremlin API: medium parity

Azure Cosmos DB for Gremlin is built on Apache TinkerPop. Standard Gremlin traversals work identically. However, Cosmos DB adds proprietary extensions (partition key semantics, bulk executor, certain graph-level operations) that TinkerPop Gremlin Server does not implement.

• Client SDK: gremlin-driver (org.apache.tinkerpop:gremlin-driver), connecting via WebSocket to port 8182, same as in production.
• Engine: tinkerpop/gremlin-server.
• Known gaps: Cosmos DB pk partition key column requirement, addE/addV Cosmos extensions, bulk import API, and multi-region graph consistency guarantees.

🟢 NoSQL / SQL API: very high parity (embedded engine)

Both NoSQL endpoints are in-process, with no Docker and instant startup:

The embedded NoSQL engine implements the Azure Cosmos DB SQL grammar in-process:

• SELECT, WHERE, ORDER BY, GROUP BY, OFFSET LIMIT, SELECT TOP, SELECT DISTINCT
• Aggregates: COUNT, SUM, AVG, MIN, MAX
• Predicates: =, !=, IN, BETWEEN, LIKE, NOT, AND, OR, IS_DEFINED, IS_NULL, CONTAINS, STARTSWITH, ENDSWITH, STRINGEQUALS, REGEXMATCH, ARRAY_CONTAINS
• Conditional: IIF(condition, trueVal, falseVal)
• String functions: LOWER, UPPER, LENGTH, CONCAT, SUBSTRING, TRIM, REPLACE, REVERSE, INDEX_OF, LEFT, RIGHT, TOSTRING, STRINGJOIN, STRINGSPLIT
• Math functions: ABS, CEILING, FLOOR, ROUND, SQRT, POWER, LOG, LOG10, EXP, SIGN, TRUNC, PI, RAND
• Array functions: ARRAY_LENGTH, ARRAY_SLICE, ARRAY_CONCAT
• Type checks: IS_STRING, IS_NUMBER, IS_BOOL, IS_ARRAY, IS_OBJECT, IS_INTEGER, IS_PRIMITIVE
• Named parameters (@name)
• Client SDK: azure-cosmos Java SDK. Enable TLS (FLOCI_AZ_TLS_ENABLED=true) and point to https://localhost:4577; fetch the runtime cert from GET /_floci/tls-cert and install it into your truststore.
• Known gaps: JOIN with nested arrays, full-text / vector search, geospatial, multi-region and RU/s governance features.