> ## 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

> Virtualize a ChromaDB collection from Node or the browser.

`ChromaVFS` mounts one ChromaDB collection, read-only, as a tree of text files:
each file is its chunks joined in order. Set up the collection's shape as in [Chroma setup](https://docs.mirage.strukto.ai/home/setup/chroma.md).

## Install

```bash theme={null}
npm install @struktoai/mirage-node chromadb
```

## Configure

```ts theme={null}
import { ChromaVFS, MountMode, Workspace } from '@struktoai/mirage-node'

const knowledge = new ChromaVFS({
  host: 'localhost',
  port: 8000,
  collectionName: 'knowledge',
})
const ws = new Workspace({ '/knowledge': knowledge }, { mode: MountMode.READ })

const result = await ws.shell('tree /knowledge && grep -rn refund /knowledge')
console.log(result.stdoutText)
await ws.close()
```

`ssl: true` reaches the server over HTTPS. A collection whose chunks name their
file and position with keys other than `page_slug` and `chunk_index` sets
`slugField` and `chunkIndexField`.

### Fields

**host** `string` (default: 'localhost')

Host name of the Chroma HTTP server.

**port** `number` (default: 8000)

Port of the Chroma HTTP server.

**ssl** `boolean` (default: false)

Connect over HTTPS instead of HTTP.

**collectionName** `string` *required*

Name of the existing Chroma collection to mount.

**slugField** `string` (default: 'page\_slug')

Chunk metadata key that holds the path of the file a chunk belongs to, relative to the mount root (`guides/quickstart.md`).

**chunkIndexField** `string` (default: 'chunk\_index')

Chunk metadata key whose integer orders a file's chunks; a chunk without one sorts as `0`.

## Layout

```text theme={null}
/knowledge/
  README.md
  guides/
    api.md
    quickstart.md
  policies/
    refunds.md
```

Paths come from the collection's path tree document, the one with the ID
`__path_tree__`: a JSON object whose keys are file paths below the mount.
Folders come from the `/` in those paths. `/knowledge/guides/quickstart.md` is
every chunk whose `page_slug` is `guides/quickstart.md`.

## Behavior

* **Read-only:** no command changes the collection.
* **Pages:** a file is its chunks sorted by chunk index and joined by line
  breaks.
* **Tree refresh:** the path tree is fetched on the first listing and reused
  until the index expires, so a change to `__path_tree__` shows up after that.
  File text is always read from Chroma.

### Vector search

The `search` CLI ranks chunks by meaning with
Chroma's vector query. Register it on the workspace:

```ts theme={null}
import { SEARCH } from '@struktoai/mirage-node'

ws.registerCli('search', SEARCH)
```

```bash theme={null}
search "how do I get started" /knowledge/
search --top-k 5 "billing policy" /knowledge/policies/
search --threshold 0.8 "billing policy" /knowledge/
```

The score is 1 minus Chroma's distance, and `--threshold` keeps the hits that
reach it. `--top-k` defaults to 10. `--method` takes only `semantic`. Each hit
prints its page and score, then the chunk.

## Browser

The same `ChromaVFS` runs in the browser from `@struktoai/mirage-browser`.

```bash theme={null}
npm install @struktoai/mirage-browser chromadb
```

```ts theme={null}
import { ChromaVFS, MountMode, Workspace } from '@struktoai/mirage-browser'

const knowledge = new ChromaVFS({
  host: 'chroma.example.com',
  port: 443,
  ssl: true,
  collectionName: 'knowledge',
})
const ws = new Workspace({ '/knowledge': knowledge }, { mode: MountMode.READ })
```

* The page calls the Chroma server directly, so the server must accept requests
  from the page's origin.

## Integration

Chroma answers this command through its own API, so fewer pages are read. See
[Integration](https://docs.mirage.strukto.ai/home/integration/overview.md).

* `grep -r` and `rg`: read only the pages with a chunk holding the text,
  which Chroma's `$contains` answers, then match each page as `grep` does. No
  match can span two chunks, so it misses nothing. `$contains` matches case,
  so `-i` reads every page.

## VFS.md

The [VFS.md](https://docs.mirage.strukto.ai/home/setup/vfs-md.md) an agent reads with Chroma mounted at `/<path>`.

> [tab] Rendered
>
> **Virtual Filesystem**
>
> | Path | Description |
> | - | - |
> | `/<path>` | `chroma`, read |
>
> **VFS Layout**
>
> **`/<path>`**
>
> * Paths are document slugs from the collection's path tree.
>
> **Supported Unix Commands for VFS**
>
> Unix commands work on each path as on a local filesystem, as far as the path supports them:
>
> | Path | Supported |
> | - | - |
> | `/<path>` | Commands that read files (`ls`, `cat`, `grep`, `find`, `jq` and the rest). `grep -r` and `rg` ask `chroma` which files may match. |
>
> **Limitations of Unix Commands for VFS**
>
> Where a path differs from a local filesystem:
>
> | Path | Limitations |
> | - | - |
> | `/<path>` | Read only: no command changes files. `grep -r`, `find` and `du` stop after 1000 files; a glob matching more, `tar -c`, `cp -r` and `rm -r` are refused. |
>
> Run `man <cmd>` or `<cmd> --help` for one command's usage.

> [tab] Raw
>
> ```markdown theme={null}
> ---
> name: workspace-filesystem
> description: The virtual filesystem layout of this workspace.
> ---
>
> # Virtual Filesystem
>
> | Path | Description |
> | --- | --- |
> | `/<path>` | `chroma`, read |
>
> ## VFS Layout
>
> ### `/<path>`
>
> - Paths are document slugs from the collection's path tree.
>
> ## Supported Unix Commands for VFS
>
> Unix commands work on each path as on a local filesystem, as far as the path supports them:
>
> | Path | Supported |
> | --- | --- |
> | `/<path>` | Commands that read files (`ls`, `cat`, `grep`, `find`, `jq` and the rest). `grep -r` and `rg` ask `chroma` which files may match. |
>
> ## Limitations of Unix Commands for VFS
>
> Where a path differs from a local filesystem:
>
> | Path | Limitations |
> | --- | --- |
> | `/<path>` | Read only: no command changes files. `grep -r`, `find` and `du` stop after 1000 files; a glob matching more, `tar -c`, `cp -r` and `rm -r` are refused. |
>
> Run `man <cmd>` or `<cmd> --help` for one command's usage.
> ```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.