> ## Documentation Index
> Fetch the complete documentation index at: https://struktoai-fix-databricks-volume-token-provider.mintlify.site/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,
    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:

```python theme={null}
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:

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

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

```python theme={null}
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:

```python theme={null}
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

```python theme={null}
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`.