Skip to main content
One Unity Catalog volume, or a folder inside it, becomes a directory tree of its files, read and written through the Databricks Files API.

Setup

Create a workspace access token, pick a volume and grant the token’s principal access to it, then export the workspace host and token.
  1. In the workspace, click the username in the top bar, then Settings, Developer, and Manage next to Access tokens.
  2. Click Generate new token and give it a name and a lifetime. A scoped token needs the files API scope. Copy the token: it is shown once.
  3. Pick a volume in Catalog Explorer. Its /Volumes/<catalog>/<schema>/<volume>/ path gives the catalog, schema and volume fields.
  4. Grant the principal USE CATALOG, USE SCHEMA and READ VOLUME, plus WRITE VOLUME for a write mount. See volume privileges.
Databricks recommends OAuth over personal access tokens; an OAuth access token works the same way.
  • DATABRICKS_HOST is the workspace origin, such as https://adb-xxxxxxxxxxxx.xx.azuredatabricks.net on Azure: http:// or https://, no path, query, fragment or user info. A trailing slash is fine.
  • token also takes a function, sync or async, that returns the current token. The function owns refresh, caching and concurrent refreshes.
  • Mirage reads no environment variables, SDK profiles or default credentials, and never retries a refused request with another credential.
  • Bind each VFS and workspace to one principal and keep caches apart across identities. Rebuild the workspace or drop its caches when the principal or its permissions change; a token refresh for the same principal keeps the VFS.

Connect

workspace.yaml

Layout

  • /dbx/reports/2026/q1/summary.md is /Volumes/main/default/agent_files/reports/2026/q1/summary.md.
  • root_path: /reports mounts only that folder of the volume; .. is refused.
  • Files keep their own names and bytes; nothing is converted.

Sample runs

On a write mount, >, cp, mv, rm and mkdir change the volume, as far as the principal’s WRITE VOLUME grant allows.

SDK guides

Python

Every config field, the VFS.md and write support.

TypeScript

Every config field, the VFS.md and write support.