---
title: Databricks Volume
icon: /images/databricks-logo.svg
description: Set up a Databricks Unity Catalog volume as a MIRAGE resource from Node.
---

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

MIRAGE ships it in `@struktoai/mirage-node` only. The TypeScript client calls
the Databricks Files REST API directly with `fetch`; the Databricks API does
not allow cross-origin browser requests, so there is no browser runtime.

For auth and environment setup, see [Databricks Volume Setup](/home/setup/databricks).

## Node

```bash
pnpm add @struktoai/mirage-node
```

```ts
import {
  DatabricksVolumeResource,
  MountMode,
  Workspace,
  normalizeDatabricksVolumeConfig,
} from '@struktoai/mirage-node'

const resource = await DatabricksVolumeResource.create(
  normalizeDatabricksVolumeConfig({
    catalog: 'main',
    schema: 'default',
    volume: 'agent_files',
    root_path: '/reports',
  }),
)
const ws = new Workspace({ '/dbx/': resource }, { mode: MountMode.READ })
const res = await ws.execute('ls /dbx/')
console.log(res.stdoutText)
```

| 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 `~/.databrickscfg` profile name. |
| `timeout` | `30` | Request timeout in seconds. |

Credentials resolve in order: explicit `host`/`token` in the config, then the
`DATABRICKS_HOST`/`DATABRICKS_TOKEN` environment variables, then the
`profile` section of `~/.databrickscfg` (or `DATABRICKS_CONFIG_PROFILE`,
falling back to `DEFAULT`).

## Filesystem layout

MIRAGE maps the configured mount prefix onto the configured volume subtree.
With `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`.

Standard shell commands like `ls`, `cat`, `head`, `tail`, `grep`, `rg`,
`find`, `tree`, `touch`, `mkdir`, `rm`, `cp`, and `mv` work through those
primitives. `mv`/`cp` are non-atomic download + upload — the Files API has no
server-side rename.

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

## Example

See `examples/typescript/databricks_volume/databricks_volume.ts`, which
mirrors `examples/python/databricks_volume/databricks_volume.py`.
