Get ThreadWeave running in under two minutes.
One command. Works on Linux, macOS, and Windows.
git clone https://github.com/PowerLooming/ThreadWeave.git cd ThreadWeave docker compose up
API available at http://localhost:8000. API docs at /docs.
Optionally run with a local LLM for smarter detection:
docker compose --profile llm up
Pulls Ollama + llama3.1:8b automatically on first start. Data persists in Docker volumes across restarts.
For development or when Docker isn't available. Requires Python 3.11+ and uv.
git clone https://github.com/PowerLooming/ThreadWeave.git cd ThreadWeave bash setup.sh
Or manually:
uv venv --python 3.11 .venv source .venv/Scripts/activate # Windows uv pip install -e ".[dev]"
Start the server:
uv run python -m threadweave.cli serve
ThreadWeave ships with:
• API server — FastAPI with auto-generated docs
• CLI — detect, search, save, serve commands
• Detection engine — Regex + optional LLM classifier
• M365 connectors — Exchange Online, SharePoint, Teams
• Google Workspace connectors — Gmail, Chat, Drive
• Confidentiality engine — Seven sensitivity levels with access enforcement
• Profiling — Latency percentiles, Prometheus export
• 925 tests — Mock-based, no external APIs called
The same installation also runs as a single-user deployment: one mailbox, one owner, everything on your machine. In that profile the email watcher reads your own mailbox as you, with delegated access, so there is no client secret and no application permission. Admin consent is needed only if your tenant blocks user consent.
export THREADWEAVE_PROFILE=personal uv run python -m threadweave.cli serve # one-time sign-in for delegated mail access uv run python -m threadweave.cli email login # reads your own mailbox, files captures in the personal tenant uv run python -m threadweave.cli email watch
What this needs: a Microsoft 365 mailbox, one Entra app registration with "Allow public client flows" enabled and the delegated Mail.Read permission, and a host to run it on. It is the same stack in a narrower profile, not a desktop app: there is no installer, and the connector set in single-user mode is the email watcher. Captures are governed by the same confidentiality levels and audit log, and grants on captured items resolve to you, because the tier performs no directory lookups.
See Can I use ThreadWeave for just my own mailbox? for the details.
The canonical description of that profile lives in the repository: docs/personal-profile.md.
After installation, follow the Setup Guide to connect your Microsoft 365 or Google Workspace account. Read the Governance FAQ for access control, confidentiality, and GDPR details. Explore the configuration guide for all thresholds and environment variables.