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
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 app client ID. Required with
refresh_token (OAuth) or with client_secret and enterprise_id (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
client_id. Box rotates it on every refresh, so persist the new one with on_refresh_token_rotated.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.Box developer token, used as is with no refresh flow; it expires after about 60 minutes. It wins over every other credential.
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.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.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.
Authentication
Set one of these credential sets:access_token: a developer token, used as is. It lasts 60 minutes, cannot be renewed by code, and wins over every other credential.client_idandrefresh_token, withclient_secretunless 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 passon_refresh_token_rotated, an async callable given each new token, to persist it across restarts.client_id,client_secretandenterprise_id: 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:
root_folder_idmounts 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.
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.