Glovebox

Glovebox is a Model Context Protocol (MCP) server that exposes read-only access to sensitive files mounted at a fixed path inside a container. Tools return metadata and aggregates only (directory listings, file stats, regex match counts, line numbers, CSV dimensions, line counts)—not raw file contents.

The design follows the “glovebox / cleanroom” idea: data stays in a bounded environment; the model receives structured summaries through tool results, not a dump of secrets.

Full documentation: browse the markdown on GitLab (index), or build the MkDocs site locally with pip install -e '.[docs]' && mkdocs serve.

Quick start (pip)

pip install mcp-glovebox

Set the root and start the MCP server on stdio:

GLOVEBOX_ROOT=/path/to/sensitive glovebox

Pre-flight check before wiring a client:

GLOVEBOX_ROOT=/path/to/sensitive glovebox --doctor
glovebox --print-config    # resolved JSON snapshot for automation

Configure your MCP client to run glovebox with GLOVEBOX_ROOT set. Copy-paste JSON for Claude Desktop and Cursor are on the MCP client examples page.

Quick start (uv)

If you manage Python projects with uv, install and run Glovebox without creating a virtual environment manually:

uv tool install mcp-glovebox

Then run it the same way:

GLOVEBOX_ROOT=/path/to/sensitive glovebox
GLOVEBOX_ROOT=/path/to/sensitive glovebox --doctor

Or run it ephemerally (no install step):

GLOVEBOX_ROOT=/path/to/sensitive uvx mcp-glovebox

Quick start (Docker)

Pull the published image (works on both linux/amd64 and linux/arm64):

docker pull touchthesun/glovebox:0.3.1

Or build locally:

docker build -t glovebox:local .

Run the MCP server on stdio (required for most MCP clients). Mount your sensitive directory read-only at /glovebox/data. Use the hardened form for any deployment against real sensitive data:

docker run --rm -i \
  --read-only \
  --tmpfs /tmp \
  --cap-drop ALL \
  --security-opt no-new-privileges \
  -v /path/to/sensitive:/glovebox/data:ro \
  touchthesun/glovebox:0.3.1

-i keeps stdin open so the client can speak MCP over stdio. See Security defaults for a full audit of what the flags do and what a naive user gets without them.

Configure your MCP client to launch this command. Copy-paste JSON templates are in MCP client examples; broader integration notes live in Integration.

Before attaching a client locally, sanity-check your mount directory:

GLOVEBOX_ROOT=/path/to/sensitive glovebox --doctor

Environment variables

Variable	Default	Meaning
GLOVEBOX_ROOT	/glovebox/data	Directory all tool paths are relative to
GLOVEBOX_MAX_OUTPUT_BYTES	256000	Upper bound on JSON size for a tool result
GLOVEBOX_MAX_SEARCH_FILE_BYTES	1048576	Files larger than this are rejected for search/aggregate
GLOVEBOX_SEARCH_BUDGET	100	Per-session ceiling on search calls (<=0 disables); bounds oracle-style reconstruction
GLOVEBOX_MIN_CELL	5	Small-cell suppression threshold; counts below this are returned as "<k" to reduce re-identification risk
GLOVEBOX_MIN_FILE_ROWS	0 (off)	Refuse search/aggregate on files below N rows/lines
GLOVEBOX_REDACT_FILENAMES	0 (off)	Hash name fields in glovebox_list responses instead of returning real filenames. Enable when filenames in the mount are themselves sensitive (e.g. patient_HIV_positive.pdf). Trade-off: directory-listing navigation is disabled; directed-analysis workflows (explicit paths) are unaffected.
GLOVEBOX_AUDIT_LOG	(stderr only)	Append JSONL audit records to this file path in addition to stderr

Built-in tools

• glovebox_list — List directory entries (name, type, size, mtime). No file contents.
• glovebox_stat — Metadata for one path. No file contents.
• glovebox_search — Regex search: count_matches or line_numbers_only. Never returns matching line text.
• glovebox_aggregate — csv: row and column counts; text: line count only. Never returns cell or line contents.

Paths are relative to GLOVEBOX_ROOT; absolute paths and escapes outside the mount are rejected.

Threat model (summary)

Primary defence — keep secrets out of filenames. Tool responses return metadata verbatim (filenames, directory structure, sizes, mtimes). Do not encode sensitive information in file or directory names; Glovebox protects file contents, not metadata. If you cannot control filenames, set GLOVEBOX_REDACT_FILENAMES=1 — see the env vars table above for the trade-off.

Glovebox reliably answers count and frequency questions (how many rows match this pattern? which lines contain this credential?) without field values entering model context. Segmented analysis over known categories is possible with multiple search calls. Statistical aggregates, value discovery, and open-ended exploration require the constrained-computation roadmap tier. See the use-case boundary analysis for a full ✓/≈/✗ breakdown across PII and code-audit scenarios.

Glovebox is one control in a larger compliance story: it minimizes what crosses into the model context but does not govern LLM providers, compromised hosts, or malicious MCP clients. See the full threat model and harness non-goals.

Development

python -m venv .venv
source .venv/bin/activate
pip install -e '.[dev]'
pytest                                          # CI also runs scripts/export_tool_manifest.py --check

Run the MCP server locally (stdio):

GLOVEBOX_ROOT=/path/to/data python -m glovebox

Pre-flight diagnostics:

GLOVEBOX_ROOT=/path/to/data python -m glovebox --doctor
python -m glovebox --print-config               # resolved JSON snapshot for automation

Documentation site locally:

pip install -e '.[docs]'
mkdocs serve

Releases and versioning

Releases follow Semantic Versioning. See CHANGELOG.md for the full history.

Tagging convention: a git tag v0.3.1 produces Docker images tagged 0.3.1 and latest. Users should pin to the versioned tag, not latest.

docker pull touchthesun/glovebox:0.3.1     # pinned — recommended
docker pull touchthesun/glovebox:latest     # floating — only for local dev

Published images are multi-arch manifests (linux/amd64 + linux/arm64). Docker automatically pulls the right variant for your host — no --platform flag needed.

To inspect what's in a manifest:

docker buildx imagetools inspect touchthesun/glovebox:0.3.1

To cut a release:

1. Update version in pyproject.toml and src/glovebox/_version.py to match.
2. Add a release entry to CHANGELOG.md.
3. Commit, then push a semver tag:

   git tag v0.3.1 && git push origin v0.3.1
   

4. In CI, manually trigger docker_push_hub (and docker_push for the GitLab registry). Both jobs require DOCKERHUB_USER / DOCKERHUB_TOKEN CI variables to be set.

Build it yourself (always available as a fallback):

docker build -t glovebox:local .

Adding tools

The four built-in tools cover the most common privacy-preserving analysis patterns. When your domain requires something more specific — a custom format parser, a domain-specific aggregate, a structured summary over a log schema the built-in regex can't meaningfully interpret — you can add a tool while preserving the no-leak contract.

Every tool in Glovebox, built-in or custom, must satisfy the same invariant: tool results serialized to JSON must never contain raw file contents, credential values, or unbounded strings drawn from the mount. The framework enforces this through three interlocking mechanisms:

• resolve_under_root (in src/glovebox/paths.py) — all file I/O must go through this function; it rejects absolute paths, .. traversals, and symlink escapes.
• check_json_size (in src/glovebox/output_limits.py) — enforces the GLOVEBOX_MAX_OUTPUT_BYTES ceiling before a result is returned.
• Contract tests (in tests/test_contract_no_leak.py) — fixture files contain a planted secret_token; the suite asserts the token never appears in serialized output.

To add a tool: use the glovebox-tool Cursor skill and the templates/tool scaffold. Run python scripts/validate_tools.py before committing, then python scripts/export_tool_manifest.py --write when tool names or schemas change.

See Custom tools for the full workflow, naming conventions, and the merge checklist.

Contributing and security

See CONTRIBUTING.md for development setup, the no-leak contract, and the PR checklist. To report a security vulnerability, follow the process in SECURITY.md — do not open a public issue.

Evaluation harness

The harness directory runs four layers of scenarios (tool surface, LLM behavior, inference, evidence). See Harness overview, harness roadmap, and CI semantics.

End-to-end validation across PyPI, Docker, and git-clone install channels:

./scripts/e2e/run_e2e.sh

See E2E validation for prerequisites, artifacts, and integration examples.

Optional Falco-sidecar notes: Hardening.