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
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.
Base URL that replaces Box’s API, upload and OAuth token hosts, such as a test server. Unset uses Box’s hosts.
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.Box app client ID. Required with
refreshToken (OAuth) or with clientSecret and enterpriseId (client credentials).Box app client secret. Required for client credentials; the OAuth refresh sends it when set, so a PKCE client can omit it.
OAuth refresh token; needs
clientId. Box rotates it on every refresh, so persist the new one with onRefreshTokenRotated.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.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 that takes the current refresh token and returns
{ accessToken, refreshToken, expiresIn }, called instead of Box’s token endpoint. Needs clientId and refreshToken.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.
Authentication
Set one of these credential sets:accessToken: a developer token, used as is. It lasts 60 minutes, cannot be renewed by code, and wins over every other credential.clientIdandrefreshToken, withclientSecretunless 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 passonRefreshTokenRotated, a function given each new token, to persist it across restarts.clientId,clientSecretandenterpriseId: client credentials for the app’s service account, fetched again on expiry with no refresh token.
write mount. In an
enterprise, a Box admin may have to enable the app first; until then Box
answers 403 access_denied.
Layout
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:
rootFolderIdmounts 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:
.boxnoteand.boxcanvascome back as the JSON Box stores, socat notes.boxnote | jq .works..gdoc,.gsheetand.gslidescome 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.tsruns the whole PKCE sign-in.
Integration
Box answers these commands through its own API, so fewer files are read. See Integration.grep -rwandrg -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: -1in the mount’s"@all"command limit reads every file instead.grep -randrgwithout-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.
- Rendered
- Raw
Virtual Filesystem
VFS Layout
/<path>- Pipe
.boxnoteand.boxcanvasfiles tojq. - Each path level resolves to a Box id with one API call on first
access;
lsthe parent before building a path.
Limitations of Unix Commands for VFSWhere a path differs from a local filesystem:
Run
man <cmd> or <cmd> --help for one command’s usage.