Skip to main content
A Dropbox account, or one folder of it, becomes a folder tree of its real files, served as raw bytes.

Setup

Create a Dropbox app, give it file permissions and trade one sign-in for a long-lived refresh token. Mirage mints the short-lived access tokens (about 4 hours) from it and renews each one 5 minutes before it expires.
  1. Open the App Console and click Create app.
  2. Choose Scoped access.
  3. Choose App folder (one folder Dropbox creates for the app, the least privilege) or Full Dropbox (the whole account).
  4. Name it (for example “Mirage”) and click Create app.
On the Permissions tab, check:Click Submit. Dropbox leaves unchecked scopes out of tokens, even when the sign-in URL asks for them.
  1. On the Settings tab, add http://localhost:1 under OAuth 2 > Redirect URIs, then copy the App key and the App secret.
  2. Open this URL in a browser, with YOUR_APP_KEY replaced. token_access_type=offline is required for a refresh token:
  3. Sign in and click Allow. The browser goes to http://localhost:1/?code=..., a page that does not load. Copy the code value and exchange it right away:
The JSON reply holds refresh_token (and expires_in: 14400 for the access token). Save the refresh token.
A browser app can skip the app secret: the TypeScript DropboxVFS from @struktoai/mirage-browser takes only clientId and refreshToken.
  1. Add http://localhost:5173/vfs/dropbox/dropbox_pkce.html to the Redirect URIs. It must match exactly, with no trailing slash.
  2. Set only DROPBOX_APP_KEY in .env.development at the repo root.
  3. Run pnpm dev in examples/browser/ and open that URL.
  4. Click Connect Dropbox.
The example keeps the refresh token in localStorage. The same token works headless as DROPBOX_REFRESH_TOKEN.
A refresh token lasts until it is revoked: the user disconnects the app at connected apps, or the app is deleted.

Connect

workspace.yaml

Layout

  • root_path (such as /Team/data) mounts one folder; an App folder app sees only its own folder.
  • Files keep their names and bytes.
  • grep -rw asks Dropbox search first; below the Professional plan it matches file names only.

Sample runs

On a write mount, tee, cp, mv, rm and mkdir change Dropbox and need files.content.write. rmdir fails with ENOTEMPTY on a non-empty folder; rm -r removes it.

SDK guides

Python

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

TypeScript

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