strukto-ai--mirage/docs/python/resource/databricks_volume.mdx

---
title: Databricks Volume
icon: folder-open
description: 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
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
DatabricksVolumeConfig(
    catalog="main",
    schema="default",
    volume="agent_files",
    root_path="/reports/2026",
)
```

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

```text
/Volumes/main/default/agent_files/reports/2026/q1/summary.md
```

appears in Mirage as:

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