Skip to main content
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.

​
Node

pnpm add @struktoai/mirage-node

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)
FieldDefaultNotes
catalogrequiredUnity Catalog catalog name.
schemarequiredUnity Catalog schema name.
volumerequiredUnity Catalog volume name.
root_path/Subdirectory inside the volume to expose.
hostnoneOptional workspace host override.
tokennoneOptional PAT override. Redacted in snapshots.
profilenoneOptional ~/.databrickscfg profile name.
timeout30Request 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 
/Volumes/main/default/agent_files/reports/2026/q1/summary.md
appears in MIRAGE as 
/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.