Databricks Volume

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.

Getting Started

Agents

Resources

Databricks Volume

Config

Mount mode

Filesystem layout

Supported operations

Shell Commands

Read Commands

Text Processing

File Operations

Path Utilities

Snapshot behavior

Databricks Apps

Example

Use Cases

​Config

​Mount mode

​Filesystem layout

​Supported operations

​Shell Commands

​Read Commands

​Text Processing

​File Operations

​Path Utilities

​Snapshot behavior

​Databricks Apps

​Example

​Use Cases

Config

Mount mode

Filesystem layout

Supported operations

Shell Commands

Read Commands

Text Processing

File Operations

Path Utilities

Snapshot behavior

Databricks Apps

Example

Use Cases