> ## 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.

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

## Config

```python theme={null}
from mirage import MountMode, Workspace
from mirage.resource.databricks_volume import (
    DatabricksVolumeConfig,
    DatabricksVolumeResource,
)

resource = DatabricksVolumeResource(DatabricksVolumeConfig(
    catalog="main",
    schema="default",
    volume="agent_files",
    root_path="/reports",
))
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.                    |
| `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`, `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

`token` is redacted in resource 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",
)
resource = DatabricksVolumeResource(config)
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

```python theme={null}
import asyncio

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

resource = DatabricksVolumeResource(DatabricksVolumeConfig(
    catalog="main",
    schema="default",
    volume="agent_files",
    root_path="/reports",
))


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