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. For auth and environment setup, see Databricks Volume Setup.

Config

import os

from mirage import MountMode, Workspace
from mirage.vfs.databricks_volume import (
	DatabricksVolumeConfig,
	DatabricksVolumeVFS,
)

vfs = DatabricksVolumeVFS(DatabricksVolumeConfig(
	catalog="main",
	schema="default",
	volume="agent_files",
	root_path="/reports",
	host=os.environ["DATABRICKS_HOST"],
	token=os.environ["DATABRICKS_TOKEN"],
))
ws = Workspace({"/dbx": vfs}, mode=MountMode.READ)

Field	Description
`timeout` default `30`	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, `schema` in a config; one path segment, no `/`.
`volume` required	Unity Catalog volume name; one path segment, no `/`.
`root_path` 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.

Mount mode

read, write or exec. Use exec if python3 or js should run scripts from the mount.

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. Given:

DatabricksVolumeConfig(
	catalog="main",
	schema="default",
	volume="agent_files",
	root_path="/reports/2026",
	host=os.environ["DATABRICKS_HOST"],
	token=os.environ["DATABRICKS_TOKEN"],
)

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. mv and cp download and upload the file. These operations are not atomic because 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.

Shell Commands

The Databricks Volume VFS supports shell commands that operate on real file content. Reads use the Files API with range requests, so commands like head -c BYTES avoid downloading the whole object. The supported set is scoped to commands that work over the volume API (no compression, encoding, or local-only utilities).

Read Commands

Command	Notes
`cat`	Read file content
`head` / `tail`	First/last N lines
`grep` / `rg`	Pattern search (file or directory level)
`jq`	Query JSON fields
`wc`	Line/word/byte counts
`stat`	File metadata (name, size, type, modified)
`find`	Recursive search with `-name`, `-maxdepth`
`tree`	Directory tree view
`nl`	Number lines

Text Processing

Command	Notes
`awk`	Pattern scanning and processing
`sed`	Stream editor
`tr`	Translate or delete characters
`sort`	Sort lines
`uniq`	Remove duplicate lines
`cut`	Extract fields/columns
`diff`	Compare files line by line

File Operations

Command	Notes
`cp`	Copy files (non-atomic download + upload)
`mv`	Move/rename files (non-atomic download + upload)
`rm`	Remove files (recursive for directories)
`mkdir`	Create directories
`touch`	Create empty file or update timestamp

Path Utilities

Command	Notes
`ls`	List directory contents

Rotating tokens

Pass a callback as token when your application refreshes access tokens:

def current_token() -> str:
	return os.environ["DATABRICKS_TOKEN"]


config = DatabricksVolumeConfig(
	catalog="main",
	schema="default",
	volume="agent_files",
	host=os.environ["DATABRICKS_HOST"],
	token=current_token,
)
vfs = DatabricksVolumeVFS(config)
ws = Workspace({"/dbx/": vfs}, mode=MountMode.READ)

This callback reads the application’s current token. Replace its body with your credential broker or token store. The callback takes no arguments and returns str or SecretStr. It can be synchronous or asynchronous. Mirage runs a synchronous callback off the event loop and awaits any returned awaitable. Mirage resolves the callback before each HTTP request, including each directory page. A deferred read stream resolves its token when the stream opens. Cached reads, construction, and snapshots do not invoke the callback. Tokens must be nonblank and contain no carriage return or newline. Your callback owns token refresh, caching, and coordination between concurrent requests. Mirage propagates provider errors and authentication failures. It does not replay a request after a 401 or fall back to profiles or default credentials. Keep each VFS and workspace bound to one principal and permission scope. Isolate file caches, indexes, and external cache prefixes across identities. If the principal or permission scope changes, rebuild the workspace or invalidate its caches. Token rotation for the same principal and scope can keep the existing VFS.

Snapshot behavior

Mirage redacts static tokens and token callbacks in VFS snapshots. Restore the mount through mounts= when loading the workspace.

Databricks Apps

Keep Mirage in-process and supply the workspace host and token explicitly. Your application’s OAuth or SDK integration can supply a token callback. This does not require FUSE. The agent accesses the mounted workspace through Mirage’s backend adapters or Workspace.shell(...).

Example

import asyncio
import os

from mirage import MountMode, Workspace
from mirage.vfs.databricks_volume import (
	DatabricksVolumeConfig,
	DatabricksVolumeVFS,
)

vfs = DatabricksVolumeVFS(DatabricksVolumeConfig(
	catalog="main",
	schema="default",
	volume="agent_files",
	root_path="/reports",
	host=os.environ["DATABRICKS_HOST"],
	token=os.environ["DATABRICKS_TOKEN"],
))


async def main() -> None:
	ws = Workspace({"/dbx/": vfs}, mode=MountMode.READ)

	r = await ws.shell("ls /dbx/")
	print(await r.stdout_str())

	r = await ws.shell("find /dbx/ -name '*.md'")
	print(await r.stdout_str())

	r = await ws.shell('head -n 20 "/dbx/q1/summary.md"')
	print(await r.stdout_str())

	r = await ws.shell('stat "/dbx/q1/summary.md"')
	print(await r.stdout_str())


if __name__ == "__main__":
	asyncio.run(main())

See:

examples/python/vfs/databricks_volume/databricks_volume.py
examples/python/agents/langchain/databricks_volume_deepagent.py

Use Cases

Agents in Databricks Apps: mount a Unity Catalog volume in-process so an agent can read and write governed files without FUSE or hardcoded credentials.
Reading governed datasets: expose a reports or dataset subtree through root_path and query it with shell commands.
Sandboxed volume access: scope an agent to a single volume (and optional root_path) so it cannot read or write outside that subtree.
Writing agent outputs back: persist generated files to the volume with write, cp, and mv.

Getting Started

Access

AI Agents

VFS

CLIs

Runtimes

Databricks Volume

Config

Mount mode

VFS.md

Virtual Filesystem

Supported Unix Commands for VFS

Limitations of Unix Commands for VFS

Supported operations

Shell Commands

Read Commands

Text Processing

File Operations

Path Utilities

Rotating tokens

Snapshot behavior

Databricks Apps

Example

Use Cases

​Config

​Mount mode

​VFS.md

​Virtual Filesystem

​Supported Unix Commands for VFS

​Limitations of Unix Commands for VFS

​Supported operations

​Shell Commands

​Read Commands

​Text Processing

​File Operations

​Path Utilities

​Rotating tokens

​Snapshot behavior

​Databricks Apps

​Example

​Use Cases

Config

Mount mode

VFS.md

Virtual Filesystem

Supported Unix Commands for VFS

Limitations of Unix Commands for VFS

Supported operations

Shell Commands

Read Commands

Text Processing

File Operations

Path Utilities

Rotating tokens

Snapshot behavior

Databricks Apps

Example

Use Cases