Originally posted on https://devblogs.microsoft.com/cosmosdb/announcing-general-availability-of-the-azure-cosmos-db-vnext-emulator/
The Azure Cosmos DB vNext emulator is generally available today. It ships as a Docker image that runs on Linux, macOS, and Windows, on both x64 and ARM64 architectures, giving you a local Cosmos DB instance you can develop and test against. Use it for inner-loop development on your laptop, in CI integration tests, and anywhere else you'd rather not use a live account.
You can get started right away with a couple of simple commands:
docker pull mcr.microsoft.com/cosmosdb/linux/azure-cosmos-emulator:vnext-latest
docker run -p 8081:8081 -p 8080:8080 -p 1234:1234 mcr.microsoft.com/cosmosdb/linux/azure-cosmos-emulator:vnext-latest
A lot has shipped since the preview announcement: broader feature and API coverage, an embedded shell, vector search, and OpenTelemetry support. The rest of this post walks through what's new at GA and how to use it.
Bootstrap and explore data with the bundled Azure Cosmos DB Shell
Azure Cosmos DB Shell is an open-source CLI for interacting with Azure Cosmos DB using bash-like commands. It's now bundled inside the emulator image, so you can drop into an interactive session against a running container without installing anything separately:
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
--rmwith an/initfolder 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 documentation has the full set of options.
Vector search for local AI development
The emulator supports vector search, 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 VectorDistance() function to get results ranked by similarity. Paired with a model running on your laptop, embeddings, storage, and retrieval all stay on the machine, which is handy when you're iterating on your application.
Try out this sample that embeds and loads data into the emulator. It uses LangChain, a popular open-source framework for building AI applications, and Ollama, a tool for running open-source models locally.
You'll need Python 3.x, and Ollama installed locally.
Start by running the emulator:
docker run --detach --name emulator \
-p 8081:8081 -p 1234:1234 \
mcr.microsoft.com/cosmosdb/linux/azure-cosmos-emulator:vnext-latest
Install Ollama, start the local server, and pull mxbai-embed-large. It produces 1024-dimension embeddings and is small enough to run comfortably on a developer laptop:
curl -fsSL https://ollama.com/install.sh | sh
ollama serve &
ollama pull mxbai-embed-large
Clone the sample and install its dependencies in a virtual environment:
git clone https://github.com/abhirockzz/cosmosdb-emulator-local-vector-search-example
cd cosmosdb-emulator-local-vector-search-example
python3 -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt
The sample reads its database name, container name, and embedding model from environment variables:
export DATABASE_NAME="docsdb"
export CONTAINER_NAME="docs"
export EMBEDDINGS_MODEL="mxbai-embed-large"
export EMBEDDING_DIMENSIONS="1024"
Now load the data. load_data.py fetches two Azure Cosmos DB documentation pages, splits them into Markdown chunks with LangChain, embeds each chunk with Ollama, and writes the chunks plus their vectors into the emulator. The container is created on first run with a vector embedding policy (/embedding, float32, cosine distance) and a DiskANN vector index.
python3 load_data.py
With the data loaded, you can run vector queries. vector_search.py takes a natural-language query, embeds it with the same local model, and runs a VectorDistance() query against the emulator container to return the top-k matching chunks by cosine similarity:
python3 vector_search.py "show me an example of a vector embedding policy"
You'll get back the most semantically relevant chunks of the source documentation, ordered by score. Try a few more queries to get a feel for what the index is doing:
python3 vector_search.py "how do I tune recall vs latency for vector queries"
python3 vector_search.py "best practices for multi-tenant vector workloads"
Other improvements
Beyond the shell and vector search, a handful of other improvements round out the GA release and make the emulator easier to plug into real workflows.
Health probe endpoint
The emulator exposes dedicated health endpoints on port 8080: /alive for liveness, /ready for readiness, and /status for detailed status.
Previously, tests, CI jobs and other components depended on the System is now fully ready to accept requests log line to know when the gateway was up. That works but is brittle. An HTTP probe is a better fit. The legacy log message is still emitted for backward compatibility, but we recommend moving to the probe.
OpenTelemetry support
The emulator supports the OpenTelemetry Protocol (OTLP) 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 live in the GitHub repo.
Broader feature and API coverage
The emulator is designed to be used with the standard Azure Cosmos DB SDKs and supports common local development scenarios. The supported API surface has grown to cover common app requirements: change feed, batch operations, JOINs, range and aggregate queries, subdocument queries, hierarchical partition keys, TTL, and an expanded set of string and array operators.
For example, you can now query deeply nested properties and guard against missing fields in a single statement:
SELECT c.username, c.profile.contact.phone
FROM c
WHERE IS_DEFINED(c.profile.contact)
See the preview enhancements post 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.
