Skip to main content
DatabricksVolumeVFS mounts one Unity Catalog volume, or one folder of it: its files and folders appear with their own names and bytes. Set up the host, token and volume grants as in Databricks setup. It ships in @struktoai/mirage-node only: Databricks refuses cross-origin browser requests, so there is no browser variant.

Install

Configure

rootPath, such as /reports, mounts one folder of the volume. Use MountMode.EXEC when python3 or js should run scripts from the mount.

Fields

number
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.
string
required
Unity Catalog catalog name; one path segment, no /.
string
required
Unity Catalog schema name; one path segment, no /.
string
required
Unity Catalog volume name; one path segment, no /.
string
default:"'/'"
Subdirectory inside the volume that becomes the mount root; .. segments are refused.
string
required
Workspace origin, http:// or https://, with no path, query, fragment or credentials.
string | function
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.

Authentication

Pass host and token explicitly: Mirage reads no environment variables, SDK profiles or default credentials. token is a personal access token or an OAuth access token, or a function, sync or async, that returns the current one, or a promise of one. A function is called before each request, including each listing page; it owns refresh, caching and concurrent refreshes.
The token’s principal needs USE CATALOG, USE SCHEMA and READ VOLUME, plus WRITE VOLUME for a write mount; a scoped token needs the files API scope. A refused request fails as Databricks answered it: Mirage never replays it after a 401 or tries another credential. Bind each VFS and workspace to one principal. Keep file caches, indexes and external cache prefixes apart across identities, and rebuild the workspace or drop its caches when the principal or its permissions change. A token refresh for the same principal keeps the VFS.

Layout

/dbx/reports/2026/q1/summary.md is /Volumes/main/default/agent_files/reports/2026/q1/summary.md. With rootPath: '/reports/2026', the same file is /dbx/q1/summary.md.

Behavior

  • Folder root: rootPath is normalized, .. segments are refused, and no path can reach above it.
  • Partial reads: reads use range requests, so head -c does not download the whole file.
  • Copy and move: the Files API has no server-side rename, so cp and mv download and upload the file and are not atomic. A directory mv removes only what it copied: a file written into the source after the copy listed it stays there, and mv fails with Directory not empty.
  • Snapshots: a snapshot never stores the token or calls a token function. Loading it needs a live mount with fresh credentials.

VFS.md

The VFS.md an agent reads with Databricks Volume mounted at /<path>. <mode> is the mount’s mode: read, write or exec. The commands shown are those of a write mount.
Virtual FilesystemSupported Unix Commands for VFSUnix commands work on each path as on a local filesystem, as far as the path supports them:Limitations of Unix Commands for VFSWhere a path differs from a local filesystem:Run man <cmd> or <cmd> --help for one command’s usage.