Databricks Volume

DatabricksVolumeVFS exposes files from a Unity Catalog volume through MIRAGE’s standard filesystem interface. Agents can list, stat, read, stream, glob, and write files under the configured volume root. MIRAGE ships it in @struktoai/mirage-node only. The TypeScript client calls the Databricks Files REST API directly with fetch; the Databricks API does not allow cross-origin browser requests, so there is no browser runtime. For auth and environment setup, see Databricks Volume Setup.

Node

pnpm add @struktoai/mirage-node

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

const vfs = await buildVfs('databricks_volume', {
  catalog: 'main',
  schema: 'default',
  volume: 'agent_files',
  root_path: '/reports',
  host: process.env.DATABRICKS_HOST,
  token: process.env.DATABRICKS_TOKEN,
})
const ws = new Workspace({ '/dbx/': vfs }, { mode: MountMode.READ })
const res = await ws.shell('ls /dbx/')
console.log(res.stdoutText)

Field	Description
`timeout` default `DEFAULT_TIMEOUT`	Seconds a request may wait to connect, or between two reads of its answer, before it fails; a download that keeps flowing is never cut off.
`catalog` required	Unity Catalog catalog name; one path segment, no `/`.
`schema` required	Unity Catalog schema name; one path segment, no `/`.
`volume` required	Unity Catalog volume name; one path segment, no `/`.
`rootPath` default `'/'`	Subdirectory inside the volume that becomes the mount root; `..` segments are refused.
`host` required	Workspace origin, `http://` or `https://`, with no path, query, fragment or credentials.
`token` required, secret	Bearer token as a string, or a function, synchronous or asynchronous, that returns one for each request.

Fields marked secret are redacted in snapshots. Pass host and token explicitly. Mirage does not discover environment variables, SDK profiles, or default credentials. An application can read its environment as shown above or use its own credential broker. For rotating credentials, pass a callback that returns a token or a promise of one. Mirage resolves it once for each outbound request, including listing pages and metadata probes. A stream resolves it when iteration starts. The provider owns token caching, refresh, and concurrent refresh coordination. Authentication failures propagate without a fallback or automatic replay.

const rotating = await buildVfs('databricks_volume', {
  catalog: 'main',
  schema: 'default',
  volume: 'agent_files',
  host: process.env.DATABRICKS_HOST,
  token: async () => broker.getAccessToken(),
})

Keep the principal and permission scope fixed for a VFS and its workspace. Different identities require isolated workspaces, file caches, indexes, and external cache prefixes. If permissions change, rebuild or invalidate those caches before further access.

VFS.md

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

Rendered
Raw

Virtual Filesystem

Path	Description
`/<path>`	`databricks_volume`, write

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>`	Almost all Unix commands.

Limitations of Unix Commands for VFS

Where a path differs from a local filesystem:

Path	Limitations
`/<path>`	`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>` | `databricks_volume`, write |

## 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>` | Almost all Unix commands. |

## Limitations of Unix Commands for VFS

Where a path differs from a local filesystem:

| Path | Limitations |
| --- | --- |
| `/<path>` | `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.

MIRAGE maps the configured mount prefix onto the configured volume subtree. With root_path: '/reports/2026' and mount prefix /dbx/, the volume path

/Volumes/main/default/agent_files/reports/2026/q1/summary.md

appears in MIRAGE as

/dbx/q1/summary.md

root_path is normalized before use, and MIRAGE rejects any virtual path that would escape above that configured subtree.

Supported operations

Reads: readdir, stat, exists, read (streamed whole or a byte range), and glob resolution. Writes: write, create, mkdir, rmdir, unlink, recursive rm, cp, and mv. Standard shell commands like ls, cat, head, tail, grep, rg, find, tree, touch, mkdir, rm, cp, and mv work through those primitives. mv/cp are non-atomic download + upload — the Files API has no server-side rename. A directory mv removes only what it copied: a file or directory written into the source after the copy listed its directory stays there, and mv fails with Directory not empty.

Snapshot behavior

token is redacted in VFS state. A callback is never called or serialized during a snapshot. Loading the snapshot requires a live VFS override with fresh credentials.

Example

See examples/typescript/vfs/databricks_volume/databricks_volume.ts, which mirrors examples/python/vfs/databricks_volume/databricks_volume.py.

Getting Started

Access

AI Agents

VFS

CLIs

Runtimes

Databricks Volume

Node

VFS.md

Virtual Filesystem

Supported Unix Commands for VFS

Limitations of Unix Commands for VFS

Supported operations

Snapshot behavior

Example

​Node

​VFS.md

​Virtual Filesystem

​Supported Unix Commands for VFS

​Limitations of Unix Commands for VFS

​Supported operations

​Snapshot behavior

​Example

Node

VFS.md

Virtual Filesystem

Supported Unix Commands for VFS

Limitations of Unix Commands for VFS

Supported operations

Snapshot behavior

Example