Chroma DB Workbench

Administer Chroma tenants, collections, and APIs — one npx away

Inspect tenants · Explore collections · Run record actions · Debug raw REST calls.

🧩 Also Available as a VS Code Extension

Prefer working inside your editor? Get the same workbench as a full sidebar panel in VS Code.

Install from Marketplace
Full sidebar workbench natively inside your editor. Browse collections, run queries, inspect records, and send raw HTTP commands — zero setup required.

Also on Open VSX

Overview

Chroma DB Workbench bundles the production Chroma admin UI inside a zero-dependency Node CLI. It launches a tiny HTTP server, injects your preferred endpoint + credentials before the page loads, and opens the workbench in your browser in seconds.

No clone. No build. No dependencies. Just npx.

npx chroma-db-workbench

Demo

Features

| | Capability | Description | |---|---|---| | 🔌 | Universal Connect | Local Chroma server, self-hosted API, or managed deployment — no config files needed | | 🧭 | Tenant & Database Switcher | Prefill tenant/database via CLI flags and swap with a single click | | 📂 | Collection Explorer | Inspect collection metadata, dimensions, and replication status instantly | | 📝 | Record Actions | Run add/upsert/delete/count/search operations with JSON payload helpers | | 🔍 | Raw API Console | Craft arbitrary REST calls against /api/v2/* with live responses | | 🔒 | API Key Injection | Pass --api-key/--api-key-header to pre-seed secure cloud sessions | | ⚡ | Zero Install | Runs through npx — no global install, no dependencies, no setup files |

Quick Start

Step 1 — Start Chroma (skip if already running)

The official Docker image exposes Chroma on container port 8000. The workbench defaults to http://localhost:8000, so map 8000:8000:

docker run --rm -p 8000:8000 ghcr.io/chroma-core/chroma:latest

If you prefer a different host port (e.g. 6333):

docker run --rm -p 6333:8000 ghcr.io/chroma-core/chroma:latest

Then launch with --url http://localhost:6333.

| Docker port mapping | Workbench endpoint | Heartbeat URL | | --- | --- | --- | | -p 8000:8000 | http://localhost:8000 | http://localhost:8000/api/v2/heartbeat | | -p 6333:8000 | http://localhost:6333 | http://localhost:6333/api/v2/heartbeat |

Step 2 — Launch the Workbench

npx chroma-db-workbench

Your browser opens automatically at a local URL, pre-connected to http://localhost:8000. Tenants, databases, and collections load instantly. ✅

Step 3 — Point it anywhere

npx chroma-db-workbench --url https://my-chroma.example --tenant playground --database analytics

Usage

npx chroma-db-workbench [options]

Options:
  -u, --url <url>           Default Chroma endpoint shown in the UI
                             (default: http://localhost:8000)
      --tenant <name>       Prefill tenant (default: default_tenant)
      --database <name>     Prefill database (default: default_database)
      --api-key <token>     Prefill API key (switches defaults to cloud mode)
      --api-key-header <h>  Prefill custom API key header (default: x-chroma-token)
  -p, --port <port>         Port to serve the UI on (default: first free from 7070)
      --host <host>         Host to bind to (default: 127.0.0.1)
      --no-open             Do not open the browser automatically
  -h, --help                Show this help
  -v, --version             Show version

Examples

| Goal | Command | |---|---| | 🚀 Default launch | npx chroma-db-workbench | | 💻 Local endpoint | npx chroma-db-workbench --url http://localhost:8000 | | ☁️ Managed cluster | npx chroma-db-workbench --url https://my-chroma.example --tenant prod --database analytics | | 🖥️ Headless / remote | npx chroma-db-workbench --host 0.0.0.0 --no-open |

Connection Reference

🖥️ Local Mode

Connect to any Chroma deployment running on your machine or internal network. No authentication headers are added.

| Field | Value | Notes | | --- | --- | --- | | Endpoint | http://localhost:8000 | Use the host port from your Docker mapping. | | Tenant | default_tenant | Default tenant for a local Chroma server. | | Database | default_database | Default database for a local Chroma server. | | Token header | x-chroma-token | Safe to leave as-is. | | Token | Leave empty | Default local Docker server does not require a token. |

Works with Docker, local binaries, or a proxy such as http://localhost:8787.

☁️ Cloud Mode

Enter your managed Chroma REST endpoint, tenant, database, and API key in the connection panel. Authentication headers are injected automatically.

Create or select a database in Chroma Cloud, then copy the connection values from the dashboard or CLI:

chroma db connect <database-name> --env-vars

| Field | Value | Notes | | --- | --- | --- | | Connection type | Cloud | Select this before connecting. | | Endpoint | CHROMA_DB_CLOUD_ENDPOINT value | Copy from Chroma Cloud settings or CLI output. | | Tenant | CHROMA_TENANT value | Copy from dashboard, CLI output, or .env. | | Database | CHROMA_DATABASE value | Copy from dashboard, CLI output, or .env. | | Token header | x-chroma-token | Required header for Chroma Cloud API calls. | | Token | CHROMA_API_KEY value | Paste the API key value, not the variable name. |

Verify the cloud token before opening the workbench:

curl "$CHROMA_DB_CLOUD_ENDPOINT/api/v2/auth/identity" \
  --header "x-chroma-token: $CHROMA_API_KEY"

Tip: Pass --api-key (and optionally --api-key-header) on the CLI so the UI opens already authenticated.

Verify Connection

Check your local server is responding before opening the workbench:

curl http://localhost:8000/api/v2/heartbeat

If you mapped a different host port, use that port in the URL:

curl http://localhost:6333/api/v2/heartbeat

Privacy: Nothing is proxied through third-party services — only your browser talks to Chroma.

CORS: Ensure your Chroma deployment allows the workbench origin (http://localhost:<port>) in its CORS policy.

Requirements

• Node.js >=18
• A running Chroma DB instance (local or cloud)
• No additional dependencies or configuration files needed

Support & Feedback

| | | |---|---| | 🌐 Project Page | Coming soon | | 🐛 Issues | Open an issue | | 🔒 Privacy Policy | Included in ui/policy/

Zero-config Chroma DB admin for builders and operators.