Skip to main content
BoxVFS mounts a Box account, or one folder of it: every item keeps its real name and raw bytes, and folders stay folders. Set up the tokens and apps as in Box setup.

Install

Configure

rootFolderId mounts one folder instead of the whole account. To try the mount quickly, pass only accessToken with a developer token.

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
Base URL that replaces Box’s API, upload and OAuth token hosts, such as a test server. Unset uses Box’s hosts.
string
default:"'0'"
Box folder ID the mount uses as its root, from the folder’s web URL (box.com/folder/<id>); unlike a path it survives renames and moves. 0 is the account root.
string
Box app client ID. Required with refreshToken (OAuth) or with clientSecret and enterpriseId (client credentials).
string
secret
Box app client secret. Required for client credentials; the OAuth refresh sends it when set, so a PKCE client can omit it.
string
secret
OAuth refresh token; needs clientId. Box rotates it on every refresh, so persist the new one with onRefreshTokenRotated.
string
Box enterprise ID for the client-credentials grant. With clientId and clientSecret, tokens are minted for the app’s service account and no refresh token is involved.
string
secret
Box developer token, used as is with no refresh flow; it expires after about 60 minutes. It wins over every other credential. Also accepted as developer_token.
function
secret
Function that takes the current refresh token and returns { accessToken, refreshToken, expiresIn }, called instead of Box’s token endpoint. Needs clientId and refreshToken.
function
secret
Function (sync or async) given the new refresh token whenever a refresh rotates it, to persist it; the token it replaces stops working after its first use.
Fields marked secret are redacted in snapshots.

Authentication

Set one of these credential sets:
  1. accessToken: a developer token, used as is. It lasts 60 minutes, cannot be renewed by code, and wins over every other credential.
  2. clientId and refreshToken, with clientSecret unless the app is a PKCE client: OAuth for a user. Box rotates the refresh token on every refresh and the old one stops working after its first use, so pass onRefreshTokenRotated, a function given each new token, to persist it across restarts.
  3. clientId, clientSecret and enterpriseId: client credentials for the app’s service account, fetched again on expiry with no refresh token.
Access tokens are renewed 5 minutes before they expire. A service account starts with an empty root: share folders with its email address to see them. The app needs the Read all files and folders stored in Box scope, and Write all files and folders stored in Box for a write mount. In an enterprise, a Box admin may have to enable the app first; until then Box answers 403 access_denied.

Layout

Box addresses items by numeric ID, and the account root is folder 0. The mount resolves each path one folder level at a time, so the first access to a nested folder costs one request per level, and keeps the result.

Behavior

  • Folder root: rootFolderId mounts one folder, its ID taken from the web URL (app.box.com/folder/<id>). Unlike a path, it survives renames and moves. Paths outside it are unreachable.
  • Box files: .boxnote and .boxcanvas come back as the JSON Box stores, so cat notes.boxnote | jq . works. .gdoc, .gsheet and .gslides come back as the Office zips Box stores (docx, xlsx, pptx). Mirage does not convert them; for an editable view of Google files, mount Google Drive instead.
  • read: fresh: a cached file is checked against the SHA-1 Box keeps, with one request. A file Box reports without a SHA-1 cannot be checked, so each fresh read downloads it again. Listings are fetched again once per command, since a folder’s version does not change with its children.

Browser

@struktoai/mirage-browser exports the same BoxVFS. It signs in with PKCE, so the page holds the client ID and a refresh token but no client secret.
  • The page’s origin must be listed in the app’s CORS domains, matched exactly; see CORS notes.
  • Save each rotated refresh token, as above, so a reload needs no new sign-in.
  • examples/browser/vfs/box/box_pkce.ts runs the whole PKCE sign-in.

Integration

Box answers these commands through its own API, so fewer files are read. See Integration.
  • grep -rw and rg -w: Box 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, or when the searched path is not a folder. Search lists how each option uses it. Box 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 Box splits differently (foo.bar) and recent writes. walk_limit: -1 in the mount’s "@all" command limit reads every file instead.
  • grep -r and rg without -w: every file is read.
  • sha1sum: the SHA-1 Box keeps, asked live.

VFS.md

The VFS.md an agent reads with Box mounted at /<path>. <mode> is the mount’s mode: read, write or exec. The commands shown are those of a write mount.
Virtual FilesystemVFS Layout/<path>
  • Pipe .boxnote and .boxcanvas files to jq.
  • Each path level resolves to a Box id with one API call on first access; ls the parent before building a path.
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.