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 tokens and apps as in Box setup.

Install

Configure

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

Fields

float
default:"30"
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.
str
Base URL that replaces Box’s API, upload and OAuth token hosts, such as a test server. Unset uses Box’s hosts.
str
Box app client ID. Required with refresh_token (OAuth) or with client_secret and enterprise_id (client credentials).
str
secret
Box app client secret. Required for client credentials; the OAuth refresh sends it when set, so a PKCE client can omit it.
str
secret
OAuth refresh token; needs client_id. Box rotates it on every refresh, so persist the new one with on_refresh_token_rotated.
str
Box enterprise ID for the client-credentials grant. With client_id and client_secret, tokens are minted for the app’s service account and no refresh token is involved.
str
secret
Box developer token, used as is with no refresh flow; it expires after about 60 minutes. It wins over every other credential.
str
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. Unset mounts the account root, folder 0.
callable
secret
Async callable that takes the current refresh token and returns (access_token, refresh_token, expires_in), called instead of Box’s token endpoint. Needs client_id and refresh_token.
callable
secret
Async callable 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. access_token: a developer token, used as is. It lasts 60 minutes, cannot be renewed by code, and wins over every other credential.
  2. client_id and refresh_token, with client_secret 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 on_refresh_token_rotated, an async callable given each new token, to persist it across restarts.
  3. client_id, client_secret and enterprise_id: 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: root_folder_id 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.

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.