> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mirage.strukto.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Chroma

> Set up the Chroma resource in Python.

## Dependencies

Install the Chroma extra:

```bash theme={null}
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 theme={null}
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 theme={null}
# .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 theme={null}
./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.