Skip to main content
DropboxVFS mounts a Dropbox account, or one folder of it: files keep their names and bytes, and folders stay folders. Set up the app key, app secret and refresh token as in Dropbox setup.

Install

Configure

rootPath, such as /Team/data, mounts one folder instead of the whole account.

Fields

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.
string
required
Dropbox app key.
string
required
secret
Dropbox app secret.
string
required
secret
Long-lived OAuth refresh token; mirage mints short-lived access tokens from it.
string
Dropbox folder the mount uses as its root, such as /Projects; unset or / is the account root. .. segments are rejected.
string
Base URL that replaces Dropbox’s OAuth, API and content hosts, such as a test server. Unset uses Dropbox’s hosts.
function
secret
Function that takes the refresh token and returns { accessToken, expiresIn } (seconds), called instead of Dropbox’s token endpoint, for example so the app secret stays on a backend.
Fields marked secret are redacted in snapshots.

Authentication

Mirage mints short-lived access tokens from the long-lived refreshToken and renews each one 5 minutes before it expires. The refresh token lasts until the user disconnects the app or the app is deleted. The app needs these scopes, checked on its Permissions tab:
  • files.metadata.read to list folders and read metadata.
  • files.content.read to download files.
  • files.content.write for writes on a write mount.
  • account_info.read for df (optional).
Dropbox leaves unchecked scopes out of tokens, and a call that needs one fails with missing_scope.

Layout

/dropbox/Projects/data.csv is the Dropbox path /Projects/data.csv, or <rootPath>/Projects/data.csv with rootPath set. An App folder app sees only its own folder.

Behavior

  • Folder root: rootPath accepts Team/data, /Team/data or /Team/data/, all the same; .. segments are rejected. Paths outside it are unreachable.
  • Folders: rmdir fails with ENOTEMPTY on a non-empty folder; rm -r removes it.
  • Files from other clients: a name missing from a cached listing is looked up on Dropbox before the mount answers that it does not exist, so a file another client created is found, and >>, touch and sed -i act on it instead of replacing it. A listing the running command fetched itself is trusted for the whole command, so one long-running command, such as a program a runtime runs, does not see a file created after it listed the folder.
  • Space: df reports the account’s space usage, with the account_info.read scope.

Browser

@struktoai/mirage-browser exports the same DropboxVFS. It signs in with PKCE, so the page holds the app key and a refresh token but no app secret.
  • Add the page’s URL to the app’s Redirect URIs on its Settings tab, such as http://localhost:5173/vfs/dropbox/dropbox_pkce.html. It must match exactly.
  • examples/browser/vfs/dropbox/dropbox_pkce.ts runs the whole PKCE sign-in and keeps the refresh token in localStorage.
  • To keep a secret on a backend instead, pass refreshFn: it takes the refresh token and returns { accessToken, expiresIn }.

Integration

Dropbox answers these commands through its own API, so fewer files are read. See Integration.
  • grep -rw and rg -w: Dropbox search names the files to read, for whole words. Every file is read when the search fails, reaches its 10,000-match limit or finds nothing. Search lists how each option uses it. Dropbox can leave out a file that holds the word:
    • Full-text search needs a Professional, Essentials or Business plan; on other plans Dropbox matches file names only.
    • Dropbox searches the text it extracted, not the bytes, and indexes a write some time after it lands, so it can miss Office files, PDFs, archives, the end of a large file, a word Dropbox splits differently (foo.bar) and recent writes.
    walk_limit: -1 in the mount’s "@all" command limit reads every file instead.
  • grep -a (--binary-files=text): files with a binary extension, such as .pdf or .zip, are read and searched as text even when the search did not name them. grep -I skips binary files.
  • find: one recursive listing.
  • du: one recursive listing.
  • ls -R and tree: one recursive listing.

VFS.md

The VFS.md an agent reads with Dropbox mounted at /<path>. <mode> is the mount’s mode: read, write or exec. The commands shown are those of a write mount.
Virtual FilesystemSupported Unix Commands for VFSUnix commands work on each path as on a local filesystem, as far as the path supports them:Limitations of Unix Commands for VFSWhere a path differs from a local filesystem:Run man <cmd> or <cmd> --help for one command’s usage.