Cosmos DB Emulator

Preview

During Public Preview you can use the Team plan for free, and get an early-adopter discount at GA. Sign in

Cosmos DB Emulator

Available on Starter Standard Team Compare plans →

Azure Cosmos DB is a globally distributed database service - storing JSON documents which you can query using SQL, along with MongoDB and Table APIs for applications which use those.

Locally supports both provisioning Cosmos DB accounts (and the databases and containers within them) and creating, querying and changing the items within them - so you can fully test your application against it.

When you provision an account in Locally, its SQL (NoSQL) API is available at https://<account>.cosmonaut.locally:5665/ - with the MongoDB and Table APIs on their own hostnames, for accounts which use them - which you can connect to using the account's connection string from the Cosmos DB SDKs and MongoDB drivers.

The SDKs work in either Gateway or Direct mode, so there's no need to change the .NET SDK's default. In Direct mode the SDK also connects to port 5681 on the same hostname.

For a step-by-step walkthrough, see Provisioning a Cosmos DB Account.

Plugin required

Locally v2026.10+ automatically installs this Resource Provider plugin when its Resource Provider is registered, but you can also install it via:

$ locally plugin install --name Microsoft.DocumentDB

Finding the Emulator

Once an account has been created, you can find its Document Endpoint on its resource page within the Locally Dashboard, along with the Cosmos DB Explorer:

Screenshot of a Cosmos DB account in the Locally Dashboard, with the Endpoints for this Service dropdown open on the Cosmos DB Explorer and Document Endpoint

The Cosmos DB Emulator

Within the Cosmos DB Explorer you can find the account's keys and connection strings, see the Request Units used on each partition, and the most recent operations - with what each one cost:

Screenshot of the Cosmos DB Explorer built into Locally, showing master keys, connection strings, RU/s throughput and recent activity

You can also browse and create databases, containers and items - and under Settings, rotate a key to check your application picks up the new one, or turn throttling off:

Screenshot of the Cosmos DB Explorer's Settings in Locally, with buttons to rotate the primary and secondary keys, and the option to disable 429 throttling

Databases and containers created in the Explorer, the Azure CLI or the Azure SDKs also appear on the account's resource page in the Locally Dashboard:

Screenshot of a Cosmos DB account in the Locally Dashboard, showing its SQL databases, its containers with their partition keys and throughput, and its Table API tables

What's Supported

The Cosmos DB emulator supports:

SQL (NoSQL) API MongoDB API Table API Change Feed Vector & Full-Text Search Stored Procedures & Triggers Transactional Batch Gateway & Direct Mode Request Unit Throttling Point-in-Time Restore

Authentication is supported using a Microsoft Entra token (checked against the account's Cosmos DB data plane role assignments), resource tokens, or the account's keys - read-only keys can only read, and an account with local authentication disabled refuses its keys.

Every request is charged Request Units against the throughput you provisioned, so going over it returns a 429 with a retry-after, as it would in Azure. The charges are close to Azure's, but not exact - so use them to spot an expensive query, rather than to size an account.

Chaos Engineering (on the Team plan) can throttle, fail, slow down or drop requests - over the SQL API, the Table API, Direct mode and the MongoDB wire protocol - or simulate a regional outage, so you can check your application copes when Cosmos DB doesn't. A fault scoped to one region fails only that region's endpoint, so the SDKs can fail over to the next, and there are faults for failover, stale reads within a session, and the responses clients retry on.

Cosmos DB also works with Locally's other emulators, as you'd expect - for example:

Examples

This end-to-end example uses the Cosmos DB emulator, and has everything you need to run it against Locally:

Differences from Azure

As of Locally v2026.11.03, the Cosmos DB emulator has the following differences from Azure:

  • Gremlin and Cassandra accounts can be created, but there's no Gremlin or Cassandra endpoint behind them.
  • Regions are always in sync, so every consistency level reads the latest write and conflicts never happen, unless you use Chaos Engineering (on the Team plan) to serve stale reads or fail an account over.
  • Partitions don't split or merge, and autoscale throughput doesn't scale with load.
  • Stored procedures have no execution time limit.
  • For MongoDB, users can't be managed over the wire protocol, and tailable cursors aren't supported.

Should you encounter any issues, please take a look at the troubleshooting section, reach out in our Discord or open an issue and we'll take a look.

Preview

During Public Preview you can use the Team plan for free, and get an early-adopter discount at GA. Sign in

A local cloud for you and your AI agents.

Your Azure infrastructure, running on your machine. Deploy in seconds, break things freely, and ship to Azure when you're ready.