> ## 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.

# Box

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

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

## Install

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

## Configure

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

const box = new BoxVFS({
  clientId: process.env.BOX_CLIENT_ID!,
  clientSecret: process.env.BOX_CLIENT_SECRET!,
  refreshToken: process.env.BOX_REFRESH_TOKEN!,
})
const ws = new Workspace({ '/box': box }, { mode: MountMode.WRITE })

const result = await ws.shell('ls /box && grep -rlw report /box/Contracts')
console.log(result.stdoutText)
await ws.close()
```

`rootFolderId` mounts one folder instead of the whole account. To try the
mount quickly, pass only `accessToken` with a
[developer token](https://docs.mirage.strukto.ai/home/setup/box.md#quick-start-developer-token-60-minutes-no-oauth).

### 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.

**endpoint** `string`

Base URL that replaces Box's API, upload and OAuth token hosts, such as a test server. Unset uses Box's hosts.

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

**clientId** `string`

Box app client ID. Required with `refreshToken` (OAuth) or with `clientSecret` and `enterpriseId` (client credentials).

**clientSecret** `string`

Box app client secret. Required for client credentials; the OAuth refresh sends it when set, so a PKCE client can omit it.

**refreshToken** `string`

OAuth refresh token; needs `clientId`. Box rotates it on every refresh, so persist the new one with `onRefreshTokenRotated`.

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

**accessToken** `string`

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

**refreshFn** `function`

Function that takes the current refresh token and returns `{ accessToken, refreshToken, expiresIn }`, called instead of Box's token endpoint. Needs `clientId` and `refreshToken`.

**onRefreshTokenRotated** `function`

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

```text theme={null}
/box/
  Contracts/
    2026_MSA.pdf
  Roadmap.gdoc
  Team Notes.boxnote
  data.csv
```

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](https://docs.mirage.strukto.ai/typescript/vfs/gdrive.md) 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.

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

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

const box = new BoxVFS({
  clientId: import.meta.env.VITE_BOX_CLIENT_ID,
  refreshToken: localStorage.getItem('box-refresh')!,
  onRefreshTokenRotated: (next) => localStorage.setItem('box-refresh', next),
})
const ws = new Workspace({ '/box': box }, { mode: MountMode.READ })
```

* The page's origin must be listed in the app's CORS domains, matched
  exactly; see [CORS notes](https://docs.mirage.strukto.ai/home/setup/box.md#cors-notes).
* Save each rotated refresh token, as above, so a reload needs no new
  sign-in.
* [`examples/browser/vfs/box/box_pkce.ts`](https://github.com/strukto-ai/mirage/blob/main/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](https://docs.mirage.strukto.ai/home/integration/overview.md).

* `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](https://docs.mirage.strukto.ai/home/integration/search.md) 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](https://docs.mirage.strukto.ai/home/limits.md#command-output) 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](https://docs.mirage.strukto.ai/home/setup/vfs-md.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.

> [tab] Rendered
>
> **Virtual Filesystem**
>
> | Path | Description |
> | - | - |
> | `/<path>` | `box`, `<mode>` |
>
> **VFS Layout**
>
> **`/<path>`**
>
> ```text theme={null}
> /<path>
>   <folder>/            # the Box folder hierarchy, mirrored
>     <name>.boxnote     # Box Note: raw ProseMirror-style JSON
>     <name>.boxcanvas   # Box Canvas: raw canvas JSON
>     <name>.gdoc        # Box's Google Workspace files, stored as
>     <name>.gsheet      #   Office Open XML (docx, xlsx, pptx):
>     <name>.gslides     #   opaque binary
>     <file>             # PDFs, images and the rest: raw bytes
> ```
>
> * 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 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 `box` 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>` | `box`, `<mode>` |
>
> ## VFS Layout
>
> ### `/<path>`
>
> ```text
> /<path>
>   <folder>/            # the Box folder hierarchy, mirrored
>     <name>.boxnote     # Box Note: raw ProseMirror-style JSON
>     <name>.boxcanvas   # Box Canvas: raw canvas JSON
>     <name>.gdoc        # Box's Google Workspace files, stored as
>     <name>.gsheet      #   Office Open XML (docx, xlsx, pptx):
>     <name>.gslides     #   opaque binary
>     <file>             # PDFs, images and the rest: raw bytes
> ```
>
> - 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 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 `box` 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.