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
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.
Subdirectory inside the volume that becomes the mount root;
.. segments are refused.Bearer token as a string, or a function, synchronous or asynchronous, that returns one for each request.
Authentication
Passhost 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.
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:
rootPathis normalized,..segments are refused, and no path can reach above it. - Partial reads: reads use range requests, so
head -cdoes not download the whole file. - Copy and move: the Files API has no server-side rename, so
cpandmvdownload and upload the file and are not atomic. A directorymvremoves only what it copied: a file written into the source after the copy listed it stays there, andmvfails withDirectory 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.
- Rendered
- Raw
Virtual Filesystem
Supported 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.