Skip to main content

​
Dependencies

Install the Chroma extra: 
cd python
uv sync --extra chroma
The resource imports chromadb lazily when it first connects to a collection. For collection schema setup, see the Chroma Setup guide.

​
Configuration

import os

from mirage import MountMode, Workspace
from mirage.resource.chroma import ChromaConfig, ChromaResource

config = ChromaConfig(
    host=os.environ.get("CHROMA_HOST", "localhost"),
    port=int(os.environ.get("CHROMA_PORT", "8000")),
    ssl=os.environ.get("CHROMA_SSL", "false").lower() == "true",
    collection_name=os.environ["CHROMA_COLLECTION"],
    slug_field=os.environ.get("CHROMA_SLUG_FIELD", "page_slug"),
    chunk_index_field=os.environ.get("CHROMA_CHUNK_INDEX_FIELD", "chunk_index"),
)
resource = ChromaResource(config=config)
ws = Workspace({"/knowledge/": resource}, mode=MountMode.READ)
Mirage connects via Chroma’s AsyncHttpClient using host, port, and ssl.

​
Config Reference

FieldRequiredDefaultDescription
collection_nameYesChroma collection name
hostNolocalhostChroma HTTP host
portNo8000Chroma HTTP port
sslNoFalseUse HTTPS for Chroma HTTP connections
slug_fieldNopage_slugChunk metadata field containing the virtual file path
chunk_index_fieldNochunk_indexChunk metadata field used to order file chunks
collection_name, slug_field, and chunk_index_field are trimmed and must not be empty.

​
Environment Example

# .env.development
CHROMA_COLLECTION=knowledge
CHROMA_HOST=localhost
CHROMA_PORT=8000
CHROMA_SSL=false
CHROMA_SLUG_FIELD=page_slug
CHROMA_CHUNK_INDEX_FIELD=chunk_index
CHROMA_EXAMPLE_QUERY=getting started

​
Run the Examples

From the repository root: 
./python/.venv/bin/python examples/python/chroma/chroma.py
./python/.venv/bin/python examples/python/chroma/chroma_vfs.py
The examples load .env.development from the repository root.