> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mirage.strukto.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Dropbox

> Virtualize a Dropbox account or folder from Node or the browser.

`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](https://docs.mirage.strukto.ai/home/setup/dropbox.md).

## Install

```bash theme={null}
npm install @struktoai/mirage-node
```

## Configure

```ts theme={null}
import { DropboxVFS, MountMode, Workspace } from '@struktoai/mirage-node'

const dropbox = new DropboxVFS({
  clientId: process.env.DROPBOX_APP_KEY!,
  clientSecret: process.env.DROPBOX_APP_SECRET!,
  refreshToken: process.env.DROPBOX_REFRESH_TOKEN!,
})
const ws = new Workspace({ '/dropbox': dropbox }, { mode: MountMode.WRITE })

const result = await ws.shell('ls /dropbox && grep -rl report /dropbox/Projects')
console.log(result.stdoutText)
await ws.close()
```

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

### Fields

**timeout** `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.

**clientId** `string` *required*

Dropbox app key.

**clientSecret** `string` *required*

Dropbox app secret.

**refreshToken** `string` *required*

Long-lived OAuth refresh token; mirage mints short-lived access tokens from it.

**rootPath** `string`

Dropbox folder the mount uses as its root, such as `/Projects`; unset or `/` is the account root. `..` segments are rejected.

**endpoint** `string`

Base URL that replaces Dropbox's OAuth, API and content hosts, such as a test server. Unset uses Dropbox's hosts.

**refreshFn** `function`

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

```text theme={null}
/dropbox/
  Photos/
  Projects/
    data.csv
    report.pdf
  notes.txt
```

`/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.

```bash theme={null}
npm install @struktoai/mirage-browser
```

```ts theme={null}
import { DropboxVFS, MountMode, Workspace } from '@struktoai/mirage-browser'

const dropbox = new DropboxVFS({
  clientId: import.meta.env.VITE_DROPBOX_APP_KEY,
  refreshToken: refreshTokenFromLocalStorage,
})
const ws = new Workspace({ '/dropbox': dropbox }, { mode: MountMode.READ })
```

* 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`](https://github.com/strukto-ai/mirage/blob/main/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](https://docs.mirage.strukto.ai/home/integration/overview.md).

* `grep -rw` and `rg -w`: [Dropbox search](https://www.dropbox.com/developers/documentation/http/documentation#files-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](https://docs.mirage.strukto.ai/home/integration/search.md) 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](https://docs.mirage.strukto.ai/home/limits.md#command-output) 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](https://docs.mirage.strukto.ai/home/setup/vfs-md.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.

> [tab] Rendered
>
> **Virtual Filesystem**
>
> | Path | Description |
> | - | - |
> | `/<path>` | `dropbox`, `<mode>` |
>
> **Supported Unix Commands for VFS**
>
> Unix commands work on each path as on a local filesystem, as far as the path supports them:
>
> | Path | Supported |
> | - | - |
> | `/<path>` | Almost all Unix commands. `grep -r` and `rg` with `-w` ask `dropbox` which files may match. |
>
> **Limitations of Unix Commands for VFS**
>
> Where a path differs from a local filesystem:
>
> | Path | Limitations |
> | - | - |
> | `/<path>` | Without `-w`, `grep -r` and `rg` read every file. `grep -r`, `find` and `du` stop after 1000 files; a glob matching more, `tar -c`, `cp -r` and `rm -r` are refused. |
>
> Run `man <cmd>` or `<cmd> --help` for one command's usage.

> [tab] Raw
>
> ```markdown theme={null}
> ---
> name: workspace-filesystem
> description: The virtual filesystem layout of this workspace.
> ---
>
> # Virtual Filesystem
>
> | Path | Description |
> | --- | --- |
> | `/<path>` | `dropbox`, `<mode>` |
>
> ## Supported Unix Commands for VFS
>
> Unix commands work on each path as on a local filesystem, as far as the path supports them:
>
> | Path | Supported |
> | --- | --- |
> | `/<path>` | Almost all Unix commands. `grep -r` and `rg` with `-w` ask `dropbox` which files may match. |
>
> ## Limitations of Unix Commands for VFS
>
> Where a path differs from a local filesystem:
>
> | Path | Limitations |
> | --- | --- |
> | `/<path>` | Without `-w`, `grep -r` and `rg` read every file. `grep -r`, `find` and `du` stop after 1000 files; a glob matching more, `tar -c`, `cp -r` and `rm -r` are refused. |
>
> Run `man <cmd>` or `<cmd> --help` for one command's usage.
> ```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.