FAQ

FAQ

Common questions about the on-prem (air-gapped) variant.

Why a separate repo from the cloud variant?

Because security should be structural, not configurational. If both variants lived in one repo with a flag like mode: airgap, every user would be one config typo away from leaking data outbound. Two repos means:

• The on-prem plugin cannot call Box APIs — there's no code path for it.
• CI scans for forbidden patterns; the build fails if any slip in.
• .mcp.json declares zero MCP servers — no out-of-band wiring possible.

See Air-Gap Trust Model for the full reasoning and Security Layers for the five enforcement layers.

Can I open a workspace created on the cloud variant with the on-prem variant (or vice versa)?

Yes. Both variants read and write the same schema — see Schema. The differences are small (file_id is null on-prem, local_path is canonical instead of optional, etc.).

A workspace created by the cloud variant can be opened by the on-prem variant as long as the underlying folder is in Box Drive. The on-prem variant ignores cloud-only fields.

A workspace created by the on-prem variant can be opened by the cloud variant; the cloud variant fills in file_id on first read after Box has synced and assigned IDs.

Does this work without internet at all?

Yes, that's the point. Once Box Drive has synced the workspace folder locally, the plugin's skills operate purely on the local filesystem. You can run the agent on an air-gapped machine, on a Faraday-caged laptop, in an SCIF — wherever, as long as the Box Drive mount is accessible.

Note: Box Drive itself needs internet to sync changes back to Box. For pure local operation with no upstream, configure Box Drive in offline mode; your changes will queue and sync when the machine reconnects.

What about the LLM? Doesn't it call out?

That's a separate concern from the plugin. The plugin makes zero network calls. Your LLM provider (Anthropic API, AWS Bedrock, Azure Government AI Foundry, local model) decides whether and where to make inference calls.

For air-gap compliance, you must pair the on-prem plugin with an air-gap-compatible LLM. See Supported LLM Configurations for the certified matrix:

• Anthropic Enterprise + BAA for HIPAA
• AWS Bedrock GovCloud for FedRAMP / IL4 / ITAR
• Azure Government AI Foundry for FedRAMP High / IL4-IL5
• Local models (Llama 3, Mistral) for total air-gap

Is there really no Box AI at all?

Correct. Box AI requires API calls to Box's inference endpoints. The air-gap envelope precludes this.

If your workflow depends on Box AI features (semantic search, AI Extract, AI Studio agents), the on-prem variant cannot help — switch to the cloud variant where appropriate. For air-gap deployments, equivalent functionality must come from:

• Your on-prem LLM via the agent runtime (Q&A, summarization, extraction prompts)
• Local tooling (pdftotext, exiftool, OCR libraries) for binary inspection
• Manual indexing via box-index-rebuild

What's the security boundary?

Inside the boundary (air-gap envelope):

• The plugin code
• Your workspace folder under the Box Drive mount
• Your local LLM or air-gap-cleared cloud LLM
• The agent runtime (Claude Code / Cowork)

Outside the boundary:

• Box (the company) — sees encrypted bytes at rest via Box Drive sync. With Box KeySafe + customer-managed keys, Box does not have content access.
• Network between Box Drive client and Box — TLS, but exposed metadata (filenames, sizes, sync times). Use Box Zones for data residency control.
• LLM providers — bound by your provider agreement. The plugin cannot enforce LLM provider's trust posture.

See Air-Gap Trust Model for what the plugin guarantees vs what it doesn't.

Can I run this without Box Drive — just on a regular filesystem?

Technically yes, but you lose:

• Multi-machine sync via Box Drive
• Box's encryption at rest
• Compliance posture from Box's certifications
• Conflict resolution via .conflict-<timestamp> files

If you want pure local memory without Box, you don't need this plugin — write your own memory layer or use a generic markdown vault. The point of this plugin is to bridge air-gap operation + Box's compliance certifications. Without Box Drive, you have neither.

How do I migrate from a cloud-only workflow?

1. Install Box Drive on a machine that has the same Box account.
2. Sync down your existing cloud-managed workspace folder.
3. Install the on-prem variant of the plugin on the air-gapped machine.
4. Point it at the synced local folder. It will read the same workspace.
5. Operate offline; Box Drive syncs changes back when you reconnect.

The workspace schema is identical, so this is a clean handoff.

Can two air-gapped machines share a workspace?

Yes, with caveats. Both machines connect to Box Drive (when online) and sync the workspace folder. Two scenarios:

• Both online, both writing: lockfile protocol arbitrates. .conflict files possible. Run box-index-rebuild after sync converges.
• One online, one offline: offline machine queues writes locally. On reconnect, Box Drive syncs the queue. Possible .conflict if the online machine also wrote.

For high-concurrency teams, treat the workspace as best-effort eventually consistent, not transactional. See Operational Notes note 1.

What's the difference vs Obsidian + Box Drive?

Obsidian is a markdown editor — no agent integration. The on-prem plugin gives an AI agent structured CRUD over a Box-Drive-backed memory store, with:

• Per-folder _index.json for instant lookup (Obsidian doesn't index for agents)
• YAML frontmatter schema for agent-readable metadata
• Companion files for binaries
• Lockfile + conflict resolution for multi-writer scenarios
• Compliance posture declarations
• CI-enforced air-gap guarantees

You can use Obsidian to view/edit the same files manually; they're plain markdown. The plugin and Obsidian don't conflict.

What's the difference vs mem0 / Supermemory?

mem0 and Supermemory are vector-store-based memory layers. They:

• Don't support enterprise compliance regimes (HIPAA, FedRAMP, ITAR) — no BAA, no FedRAMP cert
• Treat files as second-class — content gets chunked into RAG embeddings, original file stays as a blob
• Require API calls to their hosted service (or their self-hosted version with separate compliance burden)

The on-prem Box variant:

• Inherits Box's compliance certs
• Treats files as first-class — original file + companion .md describing it; agent reads either
• Zero external calls

If you don't need compliance and you want vector recall, mem0/Supermemory are simpler. If compliance matters or you need air-gap, this is the right tool.

Does this support file storage (not just .md memories)?

Yes. Any binary you put in the workspace is real Box-stored content. The plugin generates a companion .md describing the binary — what it is, what fields it has, when it was reviewed by an agent. The companion gets indexed; the original file stays as the source of truth.

See box-companion for the companion workflow.

For agents that need to read binary content (PDFs, images), the on-prem variant uses local libraries (pdftotext, exiftool, OCR if installed). For complex extraction (CAD, video, audio), the companion is sparse — file is preserved but content is not inspected. See Troubleshooting for what's supported.

Why does the plugin write to _box-memory.json not .box-memory.json?

Box Drive does not sync hidden files (anything starting with .). The leading underscore is intentional. See Operational Notes note 8.

How do I roll out to a team?

1. One person runs box-init on a Box folder. Workspace config is committed.
2. Other team members install Box Drive, collaborate on the folder via Box's normal sharing, and install the on-prem plugin.
3. Everyone uses the same workspace. Conflicts surface as .conflict- files (rare in practice).

For larger teams with multiple parallel workstreams, use box-team to carve subtrees.

What if Box (the company) gets compromised?

Box-side breach is outside the plugin's control. Mitigations available within Box's offerings:

• Box KeySafe: customer-managed encryption keys. Box cannot decrypt your data even if their infrastructure is breached.
• Box Zones: data residency in specific regions (US-East, EU-Ireland, GovCloud, etc.).
• Box Shield: threat detection on Box-side activity.

See Compliance by Deployment for the full add-on matrix.

The on-prem plugin cannot detect or react to Box-side incidents — it only sees the local mount. Operational security (rotating Box credentials, reviewing audit logs in Box Admin Console) is your responsibility.

Is the plugin code itself auditable?

Yes. The repo is public at https://github.com/mrdulasolutions/BOX-Onprem. Every release is tagged. CI checks (ci-check-airgap.sh, ci-check-schema-sync.sh) run on every PR. The 5-layer security model (see Security Layers) is enforced in CI.

For high-assurance deployments, see Designated Security Reviewer — the template for an internal security review before each release rollout in your org.

How do I report a security issue?

Do not file a public issue. Use the private security advisory flow: https://github.com/mrdulasolutions/BOX-Onprem/security/advisories/new

See SECURITY.md in the repo for response SLAs and PGP key.

See also

• Air-Gap Trust Model — the security boundary in detail
• Architecture — why this set of 9 skills, why no Box API
• Compliance by Deployment — deployment-model × regulation crosswalk
• Operational Notes — known quirks and their workarounds
• Troubleshooting — symptom-first diagnostic flows