---
title: Chroma
icon: database
description: Set up the Chroma resource in Python.
---

## Dependencies

Install the Chroma extra:

```bash
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](/home/setup/chroma) guide.

## Configuration

```python
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

| Field | Required | Default | Description |
| ----- | -------- | ------- | ----------- |
| `collection_name` | Yes | | Chroma collection name |
| `host` | No | `localhost` | Chroma HTTP host |
| `port` | No | `8000` | Chroma HTTP port |
| `ssl` | No | `False` | Use HTTPS for Chroma HTTP connections |
| `slug_field` | No | `page_slug` | Chunk metadata field containing the virtual file path |
| `chunk_index_field` | No | `chunk_index` | Chunk metadata field used to order file chunks |

`collection_name`, `slug_field`, and `chunk_index_field` are trimmed and must
not be empty.

## Environment Example

```bash
# .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:

```bash
./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.