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

> Virtualize a Databricks Unity Catalog volume from Node.

`DatabricksVolumeVFS` mounts one Unity Catalog volume, or one folder of it:
its files and folders appear with their own names and bytes. Set up the host, token and volume grants as in [Databricks setup](https://docs.mirage.strukto.ai/home/setup/databricks.md).
It ships in `@struktoai/mirage-node` only: Databricks refuses cross-origin
browser requests, so there is no browser variant.

## Install

```bash theme={null}
npm install @struktoai/mirage-node
```

## Configure

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

const dbx = await DatabricksVolumeVFS.create({
  catalog: 'main',
  schema: 'default',
  volume: 'agent_files',
  host: process.env.DATABRICKS_HOST!,
  token: process.env.DATABRICKS_TOKEN!,
})
const ws = new Workspace({ '/dbx': dbx }, { mode: MountMode.WRITE })

const result = await ws.shell("ls /dbx && find /dbx -name '*.md'")
console.log(result.stdoutText)
await ws.close()
```

`rootPath`, such as `/reports`, mounts one folder of the volume. Use
`MountMode.EXEC` when `python3` or `js` should run scripts from the mount.

### Fields

**timeout** `number` (default: DEFAULT\_TIMEOUT)

Seconds a request may wait to connect, or between two reads of its answer, before it fails; a download that keeps flowing is never cut off.

**catalog** `string` *required*

Unity Catalog catalog name; one path segment, no `/`.

**schema** `string` *required*

Unity Catalog schema name; one path segment, no `/`.

**volume** `string` *required*

Unity Catalog volume name; one path segment, no `/`.

**rootPath** `string` (default: '/')

Subdirectory inside the volume that becomes the mount root; `..` segments are refused.

**host** `string` *required*

Workspace origin, `http://` or `https://`, with no path, query, fragment or credentials.

**token** `string | function` *required*

Bearer token as a string, or a function, synchronous or asynchronous, that returns one for each request.

Fields marked secret are redacted in snapshots.

## Authentication

Pass `host` and `token` explicitly: Mirage reads no environment variables, SDK
profiles or default credentials. `token` is a personal access token or an
OAuth access token, or a function, sync or async, that returns the current
one, or a promise of one. A function is called before each request,
including each listing page; it owns refresh, caching and concurrent
refreshes.

```ts theme={null}
const dbx = await DatabricksVolumeVFS.create({
  catalog: 'main',
  schema: 'default',
  volume: 'agent_files',
  host: process.env.DATABRICKS_HOST!,
  token: async () => broker.getAccessToken(),
})
```

The token's principal needs `USE CATALOG`, `USE SCHEMA` and `READ VOLUME`,
plus `WRITE VOLUME` for a write mount; a scoped token needs the `files` API
scope. A refused request fails as Databricks answered it: Mirage never replays
it after a `401` or tries another credential.

Bind each VFS and workspace to one principal. Keep file caches, indexes and
external cache prefixes apart across identities, and rebuild the workspace or
drop its caches when the principal or its permissions change. A token refresh
for the same principal keeps the VFS.

## Layout

```text theme={null}
/dbx/
  reports/
    2026/
      q1/
        summary.md
  datasets/
    orders.csv
```

`/dbx/reports/2026/q1/summary.md` is
`/Volumes/main/default/agent_files/reports/2026/q1/summary.md`. With
`rootPath: '/reports/2026'`, the same file is `/dbx/q1/summary.md`.

## Behavior

* **Folder root:** `rootPath` is normalized, `..` segments are refused, and
  no path can reach above it.
* **Partial reads:** reads use range requests, so `head -c` does not download
  the whole file.
* **Copy and move:** the Files API has no server-side rename, so `cp` and
  `mv` download and upload the file and are not atomic. A directory `mv`
  removes only what it copied: a file written into the source after the copy
  listed it stays there, and `mv` fails with `Directory not empty`.
* **Snapshots:** a snapshot never stores the token or calls a token function.
  Loading it needs a live mount with fresh credentials.

## VFS.md

The [VFS.md](https://docs.mirage.strukto.ai/home/setup/vfs-md.md) an agent reads with Databricks Volume mounted at `/<path>`.
`<mode>` is the mount's mode: `read`, `write` or `exec`. The commands shown are
those of a `write` mount.

> [tab] Rendered
>
> **Virtual Filesystem**
>
> | Path | Description |
> | - | - |
> | `/<path>` | `<mode>` |
>
> **Supported Unix Commands for VFS**
>
> Unix commands work on each path as on a local filesystem, as far as the path supports them:
>
> | Path | Supported |
> | - | - |
> | `/<path>` | Almost all Unix commands. |
>
> **Limitations of Unix Commands for VFS**
>
> Where a path differs from a local filesystem:
>
> | Path | Limitations |
> | - | - |
> | `/<path>` | `grep -r`, `find` and `du` stop after 1000 files; a glob matching more, `tar -c`, `cp -r` and `rm -r` are refused. |
>
> Run `man <cmd>` or `<cmd> --help` for one command's usage.

> [tab] Raw
>
> ```markdown theme={null}
> ---
> name: workspace-filesystem
> description: The virtual filesystem layout of this workspace.
> ---
>
> # Virtual Filesystem
>
> | Path | Description |
> | --- | --- |
> | `/<path>` | `<mode>` |
>
> ## Supported Unix Commands for VFS
>
> Unix commands work on each path as on a local filesystem, as far as the path supports them:
>
> | Path | Supported |
> | --- | --- |
> | `/<path>` | Almost all Unix commands. |
>
> ## Limitations of Unix Commands for VFS
>
> Where a path differs from a local filesystem:
>
> | Path | Limitations |
> | --- | --- |
> | `/<path>` | `grep -r`, `find` and `du` stop after 1000 files; a glob matching more, `tar -c`, `cp -r` and `rm -r` are refused. |
>
> Run `man <cmd>` or `<cmd> --help` for one command's usage.
> ```


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