Databricks Volume

Mount a Databricks Unity Catalog volume as a filesystem.

DatabricksVolumeResource 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

from mirage import MountMode, Workspace
from mirage.resource.databricks_volume import (
    DatabricksVolumeConfig,
    DatabricksVolumeResource,
    StaticTokenProvider,
)

resource = DatabricksVolumeResource(
    DatabricksVolumeConfig(
        host="https://example.cloud.databricks.com",
        catalog="main",
        schema="default",
        volume="agent_files",
        root_path="/reports",
    ),
    token_provider=StaticTokenProvider("token"),
)
ws = Workspace({"/dbx": resource}, mode=MountMode.READ)

Field	Default	Notes
catalog	required	Unity Catalog catalog name.
schema	required	Unity Catalog schema name.
volume	required	Unity Catalog volume name.
host	required	Databricks workspace host.
root_path	/	Subdirectory inside the volume to expose.
timeout	30	Request timeout in seconds.

Credentials are supplied separately through a token provider. Mirage includes StaticTokenProvider for fixed tokens and DatabricksProfileTokenProvider for Databricks CLI profiles. Applications can implement get_token() to supply rotating or request-scoped tokens.

Mount mode

read or write.

Filesystem layout

Mirage maps the configured mount prefix onto the configured volume subtree.

Given:

DatabricksVolumeConfig(
    host="https://example.cloud.databricks.com",
    catalog="main",
    schema="default",
    volume="agent_files",
    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_bytes, read_stream, range_read, and glob resolution. Writes: write, create, mkdir, rmdir, unlink, recursive rm, cp, and mv.

mv/cp are non-atomic download + upload — the Files API has no server-side rename.

Shell Commands

The Databricks Volume resource 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

Snapshot behavior

Snapshots contain the volume location config but never the token provider. Loading a snapshot requires a full resource override for the mount:

workspace = Workspace.load(
    snapshot,
    resources={"/dbx/": resource},
)

Databricks Apps

For Databricks Apps, pass an application-owned provider. Its get_token() method can read the current request’s OBO token or return a service-principal token managed by the application:

class AppTokenProvider:
    def get_token(self) -> str:
        return current_request_token.get()


config = DatabricksVolumeConfig(
    host="https://example.cloud.databricks.com",
    catalog="main",
    schema="default",
    volume="agent_files",
)
resource = DatabricksVolumeResource(
    config,
    token_provider=AppTokenProvider(),
)
ws = Workspace({"/dbx/": resource}, mode=MountMode.READ)

This does not require FUSE. The agent can access the mounted workspace through Mirage’s backend adapters or Workspace.execute(...).

Example

import asyncio

from mirage import MountMode, Workspace
from mirage.resource.databricks_volume import (
    DatabricksProfileTokenProvider,
    DatabricksVolumeConfig,
    DatabricksVolumeResource,
)

host = "https://example.cloud.databricks.com"
resource = DatabricksVolumeResource(
    DatabricksVolumeConfig(
        host=host,
        catalog="main",
        schema="default",
        volume="agent_files",
        root_path="/reports",
    ),
    token_provider=DatabricksProfileTokenProvider(host),
)


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

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

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

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

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


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

See:

• examples/python/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.