Cosmos DB Emulator Setup for Local Gremlin Dev

Why Use the Cosmos DB Emulator?

Developing against a live Azure Cosmos DB instance costs money and requires an internet connection. The Azure Cosmos DB Emulator gives you a free, local instance that supports the Gremlin API — perfect for development, testing, and learning graph databases without any cloud costs.

Prerequisites

• Windows 10/11 or Windows Server 2016+ (the emulator is Windows-only; for macOS/Linux, use the Docker image)
• At least 2 GB of free RAM
• GremlinStudio installed on your machine

Step 1: Install the Emulator

Download the Azure Cosmos DB Emulator from the official Microsoft page. Run the installer and follow the prompts.

After installation, the emulator appears in your system tray. Right-click the tray icon and select Open Data Explorer to verify it’s running. The Data Explorer opens at https://localhost:8081/_explorer/index.html.

Step 2: Enable the Gremlin Endpoint

By default, the emulator starts with only the SQL (NoSQL) API. To enable Gremlin, you need to start it with the /EnableGremlinEndpoint flag.

Open a Command Prompt or PowerShell as Administrator and run:

"C:\Program Files\Azure Cosmos DB Emulator\CosmosDB.Emulator.exe" /EnableGremlinEndpoint

The Gremlin endpoint starts on port 8901 by default.

Important: The emulator uses a self-signed SSL certificate. For local development, GremlinStudio connects via ws:// (WebSocket without TLS) to avoid certificate issues.

Step 3: Create a Database and Graph

Open the Data Explorer at https://localhost:8081/_explorer/index.html. You may see a certificate warning — this is normal for the local emulator.

1. Click New Database and name it (e.g., graphdb)
2. Inside the database, click New Graph
3. Set the Graph Id (e.g., demo) and choose a Partition Key (e.g., /pk)
4. Click OK to create the graph

Step 4: Connect GremlinStudio

Open GremlinStudio and create a new connection profile:

Field	Value
Name	Local Emulator
Hostname	localhost
Port	8901
Database	graphdb
Graph	demo
Password	(the emulator’s primary key from the Data Explorer)
Enable SSL	Off (use ws:// not wss://)

The emulator’s default primary key is shown on the Data Explorer home page — it’s a long Base64 string that’s the same for every emulator installation.

Click Test Connection to verify. You should see a success message.

Step 5: Seed Your Graph with Data

Now that you’re connected, try creating some sample data in the GremlinStudio query editor:

g.addV('person').property('pk', 'demo').property('name', 'Alice').property('age', 30)

g.addV('person').property('pk', 'demo').property('name', 'Bob').property('age', 25)

g.addV('company').property('pk', 'demo').property('name', 'Acme Corp').property('industry', 'Technology')

Then create relationships between them:

g.V().has('name', 'Alice').addE('knows').to(g.V().has('name', 'Bob'))

g.V().has('name', 'Alice').addE('works_at').to(g.V().has('name', 'Acme Corp'))

Step 6: Explore Your Graph

Run a query to see your graph come to life:

g.V().outE()

GremlinStudio will display the vertices and edges as an interactive graph visualization. You can drag nodes, zoom in and out, and click on vertices to inspect their properties.

Try the Schema Discovery panel in the sidebar to see all vertex labels, edge labels, and property keys that exist in your graph.

Tips for Local Development

Partition keys matter. Cosmos DB requires a partition key on every vertex. Always include a pk property (or whatever you chose) when creating vertices, or you’ll get errors.

The emulator resets on restart. By default, the emulator persists data between runs, but if you need a fresh start, use the /ResetDataPath flag when launching.

Performance differs from production. The emulator is single-node and doesn’t replicate Cosmos DB’s distributed architecture. Don’t use it for performance benchmarking — use it for functional development and testing.

Use the debugger for learning. GremlinStudio’s step-by-step debugger is especially useful when learning Gremlin. Write a complex traversal, then step through it to see how each step transforms the result set.

Troubleshooting

“Connection refused” on port 8901 Make sure you started the emulator with /EnableGremlinEndpoint. The Gremlin port won’t be available with the default startup.

Certificate errors Set Enable SSL to Off in your GremlinStudio connection profile. The emulator’s self-signed certificate isn’t trusted by Gremlin.Net clients by default.

“Resource Not Found” errors Double-check your database name and graph name in the connection profile. They must match exactly what you created in the Data Explorer.

Emulator won’t start Check if another instance is already running. Only one emulator instance can run at a time. Right-click the system tray icon and select Exit before restarting.

Next Steps

With your local emulator running, you can:

• Build and test complex Gremlin queries without cloud costs
• Prototype graph schemas before deploying to Azure
• Use GremlinStudio’s AI natural language feature to generate queries
• Export your queries and deploy them against your production Cosmos DB instance

The local emulator gives you the freedom to experiment without worrying about costs or rate limits. Happy graphing!