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

> Set up a Databricks Unity Catalog volume as a MIRAGE VFS from Node.

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

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 theme={null}
pnpm add @struktoai/mirage-node
```

```ts theme={null}
import {
  DatabricksVolumeVFS,
  MountMode,
  Workspace,
  normalizeDatabricksVolumeConfig,
} from '@struktoai/mirage-node'

const vfs = await DatabricksVolumeVFS.create(
  normalizeDatabricksVolumeConfig({
    catalog: 'main',
    schema: 'default',
    volume: 'agent_files',
    root_path: '/reports',
  }),
)
const ws = new Workspace({ '/dbx/': vfs }, { mode: MountMode.READ })
const res = await ws.shell('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 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`.

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


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