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

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

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