-
Notifications
You must be signed in to change notification settings - Fork 0
Operational Notes
On-prem-specific quirks. The on-prem variant doesn't inherit the cloud variant's Box-API-side quirks (no API calls) — instead, it has its own set tied to Box Drive sync and filesystem semantics.
The cloud variant's Operational Notes documents 8 Box-API quirks. None of them apply here. This page documents the on-prem equivalents.
| # | Title | Severity | Workaround in plugin? |
|---|---|---|---|
| 1 | Box Drive sync is eventually consistent (~5–30s lag) | Medium | Partial — lockfile protocol; user must wait for sync to see remote writes |
| 2 |
.conflict-<timestamp> files on concurrent writes |
Medium | Yes — box-index-rebuild auto-merges _index.json.conflict-*
|
| 3 | Lockfile race window during Box Drive sync | Medium | Yes — 30s timeout, force-release with audit |
| 4 | Box Drive mount path varies by OS / version | Low | Yes — box-drive-detect probes common paths |
| 5 | Schema drift from cloud repo via .schema-pin
|
Low | Yes — CI fails if synced/ diverges from pinned SHA |
| 6 | macOS Finder shows Box Drive offline after sleep | Low | Yes — box-drive-detect retries; user prompted to wake |
| 7 | Long file names rejected by Box Drive (255 char limit) | Low | Yes — slug truncation at 200 chars |
| 8 | Box Drive does not sync hidden files starting with .
|
High | Yes — workspace files use _box-memory.json not .box-memory.json
|
When you write a file inside the Box Drive mount, Box Drive uploads it to Box (cloud) on a schedule — typically 5–30 seconds. Other machines pulling from the same Box folder won't see the write until their Box Drive client pulls the change. This is not transactional — there is no two-phase commit.
Implications:
- A
box-writeon machine A may not be visible tobox-recallon machine B for up to a minute. - The lockfile protocol (see Schema) is best-effort eventually consistent, not a guarantee. Two machines writing simultaneously can both think they hold the lock.
Plugin handling: box-write always writes atomically (.tmp → fsync → rename); the lockfile narrows the race window but does not eliminate it. For high-concurrency teams, run box-index-rebuild periodically to merge any .conflict files.
Box Drive's resolution when two clients write the same file before sync converges is to keep both — naming the loser <filename>.conflict-<timestamp>. The plugin sees these as separate files.
For _index.json: box-index-rebuild auto-merges. Strategy: union of entries, most-recent updated_at wins per entry ID.
For memory .md files: No auto-merge — both files exist on disk. box-index-rebuild --check lists them for user review. The user decides which to keep, or merges manually.
For _box-memory.json (workspace config): Conflict here is rare (config changes infrequently) but possible. box-index-rebuild --check flags it; user must reconcile manually before any other skill will run on the workspace.
The lockfile is itself a file in the Box Drive mount, so creating the lockfile races with Box Drive sync. Two machines creating _box-memory.lock near-simultaneously may both succeed locally; Box Drive then creates a .conflict- file for the loser.
Plugin handling: the lockfile protocol checks renewed_at — if a lockfile is >30s old, it's considered stale and force-released (logged to audit). Writers update renewed_at every 10s while holding.
Trade-off: the lockfile is advisory, not enforcing. Two writers can race past it in pathological cases. Plugin guarantees:
- Each individual write is atomic (POSIX
renamesemantics). - Lock acquires/releases are logged.
- Detected concurrent writes surface as
.conflict-files on the next sync round.
Plugin does not guarantee linearizability across machines. Treat it as best-effort cooperative coordination.
| OS | Default path |
|---|---|
| macOS |
~/Library/CloudStorage/Box-Box/ (newer) or ~/Box/ (older) |
| Windows | C:\Users\<user>\Box\ |
| Linux | Not supported by Box Drive (use Box for Linux unofficial mounts at own risk) |
Plugin handling: box-drive-detect probes a list of common paths from references/box-drive-paths.json and falls back to user prompt if none match. Detected path is cached in _box-memory.json.local_backend.mount_root.
If you have a non-standard mount, populate local_backend.mount_root manually before running box-init.
This repo pins to a specific commit of the cloud repo via .schema-pin. The synced/ directory contains files fetched from that pinned SHA.
Drift risk: if synced/schema.md (committed) doesn't match the file at the pinned SHA in mrdulasolutions/BOX, the on-prem schema may not match the cloud schema. A workspace created here could be unreadable by the cloud variant.
Plugin handling: CI workflow ci-check-schema-sync.sh fetches the pinned SHA and diffs synced/ against it. If different, the build fails — forcing whoever changed synced/ to either bump .schema-pin (sync forward) or revert.
To bump the pin: scripts/sync-shared-refs.sh <new-sha>. Updates .schema-pin and re-pulls synced/. Review the diff carefully; the new schema must remain forward/backward compatible per Schema.
After a long sleep, Box Drive sometimes shows "offline" in Finder until the Box Drive app is brought back to focus. Files may appear stale or unreadable until reconnection completes.
Plugin handling: box-drive-detect retries on transient EACCES / ENOENT for up to 30s. If still failing, surfaces the user-actionable error: "Box Drive appears offline. Open Box Drive app to reconnect."
Box's filename limit is 255 characters; with .md extension and possible -2, -3 suffix for slug collisions, the plugin truncates auto-generated slugs at 200 chars.
If you pass an explicit slug to box-write exceeding this, the call fails with a clear error rather than silently truncating.
Files starting with . are not synced by Box Drive. This means .box-memory.json would never reach Box.
The plugin uses _box-memory.json (leading underscore) precisely for this reason. Same for _index.json. Do not rename these.
If you see hidden files in your workspace and they aren't syncing, that's expected — Box Drive treats them as local-only. Don't put plugin state in hidden files.
The cloud variant's 8 quirks center on Box API behavior (search lag, OAuth scope quirks, MCP tool bugs, metadata template warm-up, Hubs warm-up). None of these apply on-prem — there is no API call to surface them.
The on-prem variant's quirks center on filesystem and sync semantics. Cloud users may never see them; on-prem users see them constantly.
If you discover an on-prem quirk we don't document:
- Open an issue at https://github.com/mrdulasolutions/BOX-Onprem/issues
- PR: add to this page and to
references/operational-notes-onprem.md(Symptom / Cause / Workaround / Implementation impact) - Cross-link from Troubleshooting if it has a user-visible symptom
- Troubleshooting — symptom-first diagnostic flows
- Box Drive Setup — mount config + sync behavior
-
Schema — lockfile protocol +
.conflictfile handling - Architecture — why we accept eventual consistency
- Cloud variant's notes: Operational Notes (for context only — none apply here)
box-memory-onprem · MIT · Repo · Latest release · Cloud variant · Cloud wiki
Getting started
Concepts
Compliance
Skills reference
- Skills Reference (all)
- box-drive-detect
- box-airgap-status
- box-init
- box-write
- box-recall
- box-companion
- box-team
- box-status
- box-index-rebuild
Operations
Project