Chroma

The Chroma VFS exposes an existing ChromaDB collection as text files mounted at a prefix such as /knowledge/. It is useful when you already have a chunked knowledge base in Chroma and want agents to use normal filesystem commands like ls, cat, grep and find, and to rank chunks by meaning with the search CLI. For collection setup, see Chroma Setup. Install the extra:

pip install "mirage-ai[chroma]"

Config

import os

from mirage import MountMode, Workspace
from mirage.vfs.chroma import ChromaConfig, ChromaVFS

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"),
)
vfs = ChromaVFS(config=config)
ws = Workspace({"/knowledge/": vfs}, mode=MountMode.READ)

The VFS is read-only. A snapshot keeps its config, and a load needs the mount handed back through mounts=; it has no drift detection, so a restored mount reads current content.

Field	Description
`host` default `'localhost'`	Host name of the Chroma HTTP server.
`port` default `8000`	Port of the Chroma HTTP server.
`ssl` default `False`	Connect over HTTPS instead of HTTP.
`collection_name` required	Name of the existing Chroma collection to mount.
`slug_field` 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`).
`chunk_index_field` default `'chunk_index'`	Chunk metadata key whose integer orders a file’s chunks; a chunk without one sorts as `0`.

VFS.md

The VFS.md an agent reads with Chroma mounted at /<path>.

Rendered
Raw

Virtual Filesystem

Path	Description
`/<path>`	`chroma`, read

`/<path>` layout

Chroma is mounted as a read-only virtual filesystem backed by a ChromaDB
collection.

Use cat, head, tail, ls, find, tree, and grep to inspect indexed documents.
Paths are document slugs from the collection path tree. Writes are not
supported.

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.

---
name: workspace-filesystem
description: The virtual filesystem layout of this workspace.
---

# Virtual Filesystem

| Path | Description |
| --- | --- |
| `/<path>` | `chroma`, read |

## `/<path>` layout

```text
Chroma is mounted as a read-only virtual filesystem backed by a ChromaDB
collection.

Use cat, head, tail, ls, find, tree, and grep to inspect indexed documents.
Paths are document slugs from the collection path tree. Writes are not
supported.
```

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

Chroma paths come from the path tree document stored in the collection with ID __path_tree__. The document body must be a JSON object whose keys are virtual file paths below the mount prefix.

{
  "README.md": {
    "size": 1024
  },
  "guides/quickstart.md": {
    "size": 4096,
    "updated_at": "2026-01-03T00:00:00Z"
  }
}

Mounted at /knowledge/, this becomes:

/knowledge/
  README.md
  guides/
    quickstart.md

Mirage infers folders from path segments and stores the tree in the index cache. The size, created_at, and updated_at metadata values are used by tree and listing operations when present.

Reading Documents

Each file is assembled from Chroma chunk documents whose metadata slug matches the path. Chunks are sorted by the configured chunk index field and joined with a single newline.

ls /knowledge/
tree /knowledge/
find /knowledge/ -type f
cat /knowledge/guides/quickstart.md
head -n 20 /knowledge/guides/quickstart.md
tail -n 20 /knowledge/guides/quickstart.md
grep -rin "billing" /knowledge/

Exact Search with Grep

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. A page is its chunks joined by line breaks, so no match can span two chunks and the answer is exact. $contains matches case, so -i reads every page.

grep -r "refund" /knowledge/policies/
grep -ri "quickstart" /knowledge/
grep -n "API key" /knowledge/guides/quickstart.md

Vector Search

The search CLI asks Chroma’s vector query API. Use it when semantic similarity matters more than exact text matching. Register it on the workspace:

from mirage.commands.cli.builtin.search import SEARCH

ws.register_cli("search", SEARCH)

search "how do I get started" /knowledge/
search --top-k 5 "billing policy" /knowledge/policies/
search --top-k 3 "API authentication" /knowledge/guides/quickstart.md
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:

/knowledge/guides/quickstart.md:0.82
Use an API key to authenticate requests.

Cache

The VFS uses Mirage’s index cache for the virtual tree. The first directory listing or path resolution fetches __path_tree__; later ls, find, tree, and path resolution reuse the cached tree until the index cache expires or the workspace is recreated. File content is still read from Chroma when commands materialize document text.

Integration

What Chroma answers through its own API, so fewer files are read. Integration explains each command.

Command	On Chroma
`grep -r`, `rg`	Chroma `$contains` over the chunks, for any text; `-i` reads every page. It misses nothing.

Examples

Runnable examples live under examples/python/vfs/chroma/:

chroma.py — command workflow with ls, tree, find, cat, head, tail, grep, and search.
chroma_vfs.py — in-process VFS workflow with os.listdir(), open(), and os.path.*.

Shell Commands

Command	Notes
`ls`	List folders and files from the path tree
`tree`	Print the mounted path tree
`find`	Search the virtual tree by name, type, depth, and size
`cat`	Read full file text assembled from Chroma chunks
`head` / `tail`	Read the first or last lines/bytes
`grep`	Exact or regex matching over assembled file text

Getting Started

Access

AI Agents

VFS

CLIs

Runtimes

Config

VFS.md

Virtual Filesystem

`/<path>` layout

Supported Unix Commands for VFS

Limitations of Unix Commands for VFS

Reading Documents

Exact Search with Grep

Vector Search

Cache

Integration

Examples

Shell Commands

​Config

​VFS.md

​Virtual Filesystem

​/<path> layout

​Supported Unix Commands for VFS

​Limitations of Unix Commands for VFS

​Reading Documents

​Exact Search with Grep

​Vector Search

​Cache

​Integration

​Examples

​Shell Commands

Config

VFS.md

Virtual Filesystem

`/<path>` layout

Supported Unix Commands for VFS

Limitations of Unix Commands for VFS

Reading Documents

Exact Search with Grep

Vector Search

Cache

Integration

Examples

Shell Commands