Box

The Box resource mounts a Box account at some prefix such as /box/. All operations involve network I/O to the Box v2 HTTP API: /2.0/folders/{id}/items for directories, /2.0/files/{id}/content for content, and multipart upload / /2.0/folders / delete / PUT (rename or move) / copy for writes. Files are served as raw bytes. Both READ and WRITE modes are supported. Box addresses everything by numeric item id, not by path (the account root is folder id 0). Mirage resolves each path to its id by listing folders level by level and caches the path → id mapping, so nested directories cost one API call per level on first access. Box-native documents are decoded to clean JSON on read: .boxnote and .boxcanvas surface as <name>.boxnote.json / <name>.boxcanvas.json, and Box’s Google-Workspace files (.gdoc / .gsheet / .gslides) surface as <name>.<kind>.json with the server-extracted text in body_text.

Box’s .gdoc.json shares the vfs suffix with Google Drive’s, but the payload is different. Box stores these files as Office Open XML (docx / xlsx / pptx) and Mirage reads them through Box’s representations API (extracted_text), returning a small envelope with body_text. Google Drive reads them through Google’s Documents API and returns the full rich Document structure. The gws commands (gws docs documents get and friends) work only on Google mounts: the ids are Google ids, and Box exposes no Docs-style edit API for these files. On a Box mount, use cat ... | jq -r .body_text for the text; for rich reads or edits, mount the file’s Google counterpart via Google Drive.

For credential setup, see the Box Setup guide. The TypeScript packages ship the same backend for Node and the browser, see Box (TypeScript).

Config

import os

from mirage import MountMode, Workspace
from mirage.resource.box import BoxConfig, BoxResource

config = BoxConfig(
    # A Box developer token from the app console (~60-minute lifetime):
    access_token=os.environ["BOX_ACCESS_TOKEN"],
    # Optional:
    # root_folder_id="123456789",  # mount a sub-folder as the root
)

resource = BoxResource(config)
ws = Workspace({"/box": resource}, mode=MountMode.WRITE)

Box supports three authentication modes:

Developer token (access_token): quickest to try; expires after ~60 minutes and cannot be refreshed programmatically.
OAuth2 refresh (client_id + refresh_token, optional client_secret): Box rotates the refresh token on each refresh; supply on_refresh_token_rotated to persist the new one across restarts.
Client credentials (client_id + client_secret + enterprise_id): the app authenticates as its own service account; expired tokens are simply re-fetched.

The access token is cached in memory and refreshed ~5 minutes before expiry (refresh and client-credentials modes).

Config Reference

Field	Required	Description
`access_token`	One of*	Box developer token (skips the refresh flow)
`client_id`	One of*	Box app client id (with `refresh_token`, or with `client_secret`+`enterprise_id`)
`client_secret`	No	Box app client secret
`refresh_token`	One of*	Long-lived OAuth2 refresh token (with `client_id`)
`enterprise_id`	No	Enterprise id for the client-credentials grant
`root_folder_id`	No	Mount a sub-folder as the root (default `0`, the account root)
`endpoint`	No	Base URL overriding the real `api.box.com` hosts (test fakes)

* Provide one of: access_token; client_id + refresh_token; or client_id + client_secret + enterprise_id.

Mount a subfolder

Pass root_folder_id to expose a single Box folder as the mount root instead of the whole account. Every command and FUSE/VFS op is scoped to that folder; paths outside it are unreachable. Folder ids are stable across renames and moves, and are visible in the Box web URL (app.box.com/folder/<id>), so an id-based mount survives reorganization that a path prefix would not.

config = BoxConfig(
    access_token=os.environ["BOX_ACCESS_TOKEN"],
    root_folder_id="123456789",
)

Cache

The Box resource caches directory listings via IndexCacheStore (24-hour TTL) to hold the path → id mapping and reduce repeated API calls during traversal; file reads go through the standard read cache (caches_reads = True). Writes invalidate the affected listings so subsequent reads see the new state.

Example

import asyncio
import os

from mirage import MountMode, Workspace
from mirage.resource.box import BoxConfig, BoxResource

config = BoxConfig(access_token=os.environ["BOX_ACCESS_TOKEN"])

resource = BoxResource(config)


async def main() -> None:
    ws = Workspace({"/box": resource}, mode=MountMode.WRITE)

    r = await ws.execute("ls /box/")
    print(await r.stdout_str())

    r = await ws.execute("grep -rl report /box/docs/")
    print(await r.stdout_str())

    # Plain text from a Box Note:
    r = await ws.execute("cat /box/notes/standup.boxnote.json | jq -r .body_text")
    print(await r.stdout_str())

    await ws.close()


asyncio.run(main())

Getting Started

Agents

Resources

Runtimes

Config

Config Reference

Mount a subfolder

Cache

Example

​Config

​Config Reference

​Mount a subfolder

​Cache

​Example

Config

Config Reference

Mount a subfolder

Cache

Example