Chroma

ChromaVFS exposes a ChromaDB collection as a read-only filesystem: the directory tree comes from the collection’s __path_tree__ document, pages are chunk sets joined in chunk_index order, and vector retrieval is the search CLI. The TypeScript backend mirrors the Python one and returns identical results.

Node

The chromadb client is an optional peer dependency; install it alongside Mirage:

pnpm add @struktoai/mirage-node chromadb

import { ChromaVFS, MountMode, SEARCH, Workspace } from '@struktoai/mirage-node'

const knowledge = new ChromaVFS({
  config: {
    host: 'localhost',
    port: 8000,
    collectionName: 'knowledge',
    // slugField: 'page_slug',      (default)
    // chunkIndexField: 'chunk_index', (default)
  },
})

const ws = new Workspace({ '/knowledge': knowledge }, { mode: MountMode.READ })
ws.registerCli('search', SEARCH)

console.log(await (await ws.shell('tree /knowledge/')).stdoutStr())
console.log(await (await ws.shell('grep -r refund /knowledge/policies/')).stdoutStr())
console.log(
  await (await ws.shell('search "how am I throttled" /knowledge/')).stdoutStr(),
)

grep pushes $contains / $regex filters down to ChromaDB before fine filtering locally, so recursive searches avoid fetching the whole collection. search takes --top-k, --threshold and --method as it does in Python.

Config

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.
`collectionName` required	Name of the existing Chroma collection to mount.
`slugField` 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` 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.

Getting Started

Access

AI Agents

VFS

CLIs

Runtimes

Node

Config

VFS.md

Virtual Filesystem

`/<path>` layout

Supported Unix Commands for VFS

Limitations of Unix Commands for VFS

​Node

​Config

​VFS.md

​Virtual Filesystem

​/<path> layout

​Supported Unix Commands for VFS

​Limitations of Unix Commands for VFS

Node

Config

VFS.md

Virtual Filesystem

`/<path>` layout

Supported Unix Commands for VFS

Limitations of Unix Commands for VFS