> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mirage.strukto.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Databricks Volume

> Mount a Databricks Unity Catalog volume as a filesystem.

`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](/home/setup/databricks).

## Config

```python theme={null}
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",
))
ws = Workspace({"/dbx": vfs}, mode=MountMode.READ)
```

| Field | Default | Notes |
| - | - | - |
| `catalog` | required | Unity Catalog catalog name. |
| `schema` | required | Unity Catalog schema name. |
| `volume` | required | Unity Catalog volume name. |
| `root_path` | `/` | Subdirectory inside the volume to expose. |
| `host` | `None` | Optional workspace host override. |
| `token` | `None` | Optional PAT override. Redacted in snapshots. |
| `profile` | `None` | Optional Databricks SDK profile name. |
| `timeout` | `30` | Request timeout in seconds. |

## Mount mode

`read` or `write`.

## Filesystem layout

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

Given:

```python theme={null}
DatabricksVolumeConfig(
    catalog="main",
    schema="default",
    volume="agent_files",
    root_path="/reports/2026",
)
```

and mount prefix `/dbx/`, the volume path:

```text theme={null}
/Volumes/main/default/agent_files/reports/2026/q1/summary.md
```

appears in Mirage as:

```text theme={null}
/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` (whole or a byte range),
`read_stream`, 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 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 |

## Snapshot behavior

`token` is redacted in VFS state. Loading a snapshot back requires an
override config that provides fresh credentials if the runtime auth chain does
not already supply them.

## Databricks Apps

For Databricks Apps, prefer SDK-default auth and keep Mirage in-process:

```python theme={null}
config = DatabricksVolumeConfig(
    catalog="main",
    schema="default",
    volume="agent_files",
)
vfs = DatabricksVolumeVFS(config)
ws = Workspace({"/dbx/": vfs}, mode=MountMode.READ)
```

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

## Example

```python theme={null}
import asyncio

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",
))


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/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`.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.