Announcing General availability of the Azure Cosmos DB vNext emulator

docker exec -it <container-name> cosmoshell.sh

The wrapper auto-detects the emulator endpoint and authenticates with the well-known account key.

Before this, getting a known dataset into the emulator usually meant an extra script in your test setup: wait for the gateway to come up, then create databases, containers, and seed documents. Thanks to the Azure Cosmos DB Shell integration, the emulator runs any .csh scripts at the top level of /init in alphabetical order before the emulator is ready to accept requests. The bootstrap step moves out of your application and into the container itself.

This is useful for many scenarios, including:

• 
  CI integration tests. Every job starts from an identical, deterministic dataset, with no app-side bootstrap and no readiness polling.


• 
  Local dev reset. Pair --rm with an /init folder for a one-command reset back to a known state between runs.


• 
  Demos and tutorials. Ship fixture scripts next to your sample so readers see real data on first run, not an empty database.


• 
  Bug repros. Capture a problematic dataset as a small folder of scripts and attach it to an issue.

The example below sets up a ShopDB with Users and Orders containers, both partitioned on /customerId so a customer's orders co-locate with their profile. It uses separate scripts for each step.

01-init.csh creates the database and both containers. Adding cd ShopDB at the end means later scripts don't have to repeat --database=ShopDB on every line, since the shell session is shared across files.

mkdb ShopDB

mkcon Users /customerId --database=ShopDB

mkcon Orders /customerId --database=ShopDB

cd ShopDB

02-load.csh inserts a couple of users and a few of their orders:

mkitem -container Users '{"id":"u1","customerId":"u1","name":"Alice","tier":"gold"}'

mkitem -container Users '{"id":"u2","customerId":"u2","name":"Bob","tier":"silver"}'

mkitem -container Orders '{"id":"o1","customerId":"u1","total":129.50,"status":"shipped"}'

mkitem -container Orders '{"id":"o2","customerId":"u1","total":42.00,"status":"pending"}'

mkitem -container Orders '{"id":"o3","customerId":"u2","total":18.75,"status":"shipped"}'

Mount the folder at /init and start the container:

docker run --name emulator --rm -e ENABLE_INIT_DATA=true \

-v "$(pwd):/init" -p 8081:8081 -p 1234:1234 \

mcr.microsoft.com/cosmosdb/linux/azure-cosmos-emulator:vnext-latest

By the time the emulator is up, both containers are populated and queryable. Verify with a one-liner that pulls Alice's orders:

docker exec emulator cosmoshell.sh -c \

'query "SELECT c.id, c.total, c.status FROM c WHERE c.customerId = '\''u1'\''" --container=Orders --database=ShopDB'

If you just want a quick look without writing any scripts, the image also ships with example seed scripts under /scripts/init_examples/ that load automatically when ENABLE_INIT_DATA=true is set. Or, if you need the seeded state to survive container restarts, bind-mount a host folder at /data and the emulator will skip initialization on subsequent runs. The , so you can build and iterate on RAG and semantic-search workloads locally. Define a vector embedding policy on the container, add a matching vector index, and write the embedding alongside the rest of your document:

{

  "vectorEmbeddingPolicy": {

    "vectorEmbeddings": [

      { "path": "/embedding",

        "dataType": "float32",

        "distanceFunction": "cosine",

        "dimensions": 1024

      }

    ]

  }

}

Then, you can execute semantic search queries using the , a popular open-source framework for building AI applications, and for exporting telemetry. With --enable-otlp (or ENABLE_OTLP_EXPORTER=true), it emits request rates, query execution times, resource utilization, and error rates that you can pipe into any OTLP-compatible backend. For quick debugging without a collector, --enable-console (or ENABLE_CONSOLE_EXPORTER=true) prints telemetry to stdout. Conditional TLS is supported on the OTLP exporter, so the emulator can be wired into observability stacks that require secure transport. Detailed setup and examples for more query walkthroughs across JOINs, operators, and subdocuments.

A few endpoints that aren't core to data operations (offers, users, permissions, etc.) are now accepted as no-ops. They return valid HTTP status codes but don't perform the underlying operation, so application code that happens to touch them won't break when pointed at the emulator.

Get started

The Azure Cosmos DB Linux emulator is generally available today. Pull the GA image and you have a local Azure Cosmos DB endpoint to develop and test against, right on your machine and without an Azure subscription.

docker pull mcr.microsoft.com/cosmosdb/linux/azure-cosmos-emulator:vnext-latest

If you hit an issue or have a feature request, please open it on the GitHub repository.