During Public Preview you can use the Team plan for free, and get an early-adopter discount at GA. Sign in
Cosmos DB Emulator
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.
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:
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:
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:
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:
What's Supported
The Cosmos DB emulator supports:
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:
- The change feed drives Cosmos DB triggers in the Function App Emulator.
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.
During Public Preview you can use the Team plan for free, and get an early-adopter discount at GA. Sign in