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
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.
Dropbox folder the mount uses as its root, such as
/Projects; unset or / is the account root. .. segments are rejected.Base URL that replaces Dropbox’s OAuth, API and content hosts, such as a test server. Unset uses Dropbox’s hosts.
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.Authentication
Mirage mints short-lived access tokens from the long-livedrefreshToken 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.readto list folders and read metadata.files.content.readto download files.files.content.writefor writes on awritemount.account_info.readfordf(optional).
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:
rootPathacceptsTeam/data,/Team/dataor/Team/data/, all the same;..segments are rejected. Paths outside it are unreachable. - Folders:
rmdirfails withENOTEMPTYon a non-empty folder;rm -rremoves 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
>>,touchandsed -iact 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:
dfreports the account’s space usage, with theaccount_info.readscope.
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.tsruns the whole PKCE sign-in and keeps the refresh token inlocalStorage.- 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 -rwandrg -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: -1in the mount’s"@all"command limit reads every file instead. -
grep -a(--binary-files=text): files with a binary extension, such as.pdfor.zip, are read and searched as text even when the search did not name them.grep -Iskips binary files. -
find: one recursive listing. -
du: one recursive listing. -
ls -Randtree: 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.
- Rendered
- Raw
Virtual Filesystem
Supported 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.