Local‑first capture, organize, and search for links and notes. brainbox is a desktop app built with Tauri (Rust) and React that keeps your data on your machine, with fast full‑text search and handy capture flows.
⚠️ EDUCATIONAL/LEARNING PROJECT This is an open source learning project demonstrating desktop app development with Tauri, React, and Rust. It is NOT intended for production use with sensitive data.
📚 Purpose brainbox serves as a comprehensive example of:
- Building cross-platform desktop apps with Tauri 2
- Implementing full-text search with Tantivy
- Local-first data storage with SQLite
- Client-side encryption with proper key derivation
- React + TypeScript frontend architecture
- Release checks and protocol handlers
- Vaults: create, rename, cover images, delete, and reorder items per vault.
- Capture: add notes or URLs; auto-detects URLs and enriches with OpenGraph metadata.
- Previews: YouTube thumbnails, site favicon, and title/description extraction.
- Search: local full‑text search powered by Tantivy (BM25 ranking).
- AI (brainy): intelligent assistant with tool calling capabilities — can create notes, search vaults, fetch web content, and organize items. Supports multiple providers (Ollama, OpenAI, Anthropic, Google, OpenRouter).
- Hotkey: global capture hotkey (Windows) to pop open the capture modal.
- Protocol:
brainbox://capture?url=...&title=...handler (Windows) for one‑click sends. - Tray: system tray icon with show/hide/quit actions.
- Update checks: detects newer published GitHub releases; installation is manual.
- Local‑first: data stored in a local SQLite database; no cloud required.
- Desktop: Tauri 2 (Rust), plugins: global_shortcut and single_instance.
- Backend: Rust (
rusqlite,tantivy,reqwest,quick-xml,chacha20poly1305). - Frontend: React 18, TypeScript, Vite.
- Styling: CSS tokens, themes, and custom component library.
- Node.js 18+ with Corepack/pnpm.
- Rust (stable) and Tauri system prerequisites for your OS:
- Windows: Visual Studio Build Tools, WebView2.
- macOS: Xcode Command Line Tools.
- See: https://tauri.app/start/prerequisites/
corepack enable
pnpm installDownload from Releases
- Go to GitHub Releases
- Download the appropriate artifact for your platform:
- Windows:
brainbox-portable.exe - macOS:
.dmgfile (Apple Silicon M1/M2/M3+ only)
- Windows:
The Windows portable executable is unsigned and may trigger SmartScreen or antivirus warnings. macOS DMGs are signed, notarized, and stapled. Verify the matching SHA-256 manifest before running either artifact.
pnpm tauri devVite is configured for Tauri at http://127.0.0.1:17341 with strict port matching.
pnpm devThis runs the frontend in a browser without Tauri backend features.
pnpm tauri buildBuild artifacts (installers/bundles) are created via Tauri for your platform.
pnpm run verifyThis runs the frontend production build, unit tests, and Playwright smoke tests.
pnpm run smoke:tauriThis builds the real Tauri debug binary without bundling, starts the Vite dev server it expects, launches the desktop app with an isolated temporary BRAINBOX_DATA_DIR, verifies that the app initializes its SQLite DB and search index, then closes both processes.
Release gates and manual desktop QA are tracked in docs/release-readiness.md.
brainbox can check the latest published GitHub release and report a newer version. Download and installation are manual until signed Tauri updater artifacts and previous-version upgrade proof are in place.
- Launch the app and create a new vault from the UI.
- Each vault stores items (notes/URLs) encrypted at rest in a local SQLite DB.
- Click Capture to add a note or paste a URL.
- URLs get enriched with title/description and a preview image when available.
- YouTube links automatically use a high‑quality thumbnail.
- Use the search bar to find items across vaults via Tantivy full‑text search.
brainy is an intelligent assistant built into brainbox with full tool calling capabilities.
Features:
- Summarize notes and captured links automatically
- Create, update, and organize vault items via natural language
- Search across your vaults
- Fetch and process web content and YouTube transcripts
- Move items between vaults
Supported Providers:
| Provider | Type | Tool Calling |
|---|---|---|
| Ollama | Local | Prompt-based |
| LM Studio | Local | Prompt-based |
| OpenAI | Cloud | Native |
| Anthropic | Cloud | Native |
| Google Gemini | Cloud | Native |
| OpenRouter | Cloud | Native |
Setup:
- Configure under Settings → AI: select a provider and enter credentials if needed.
- For local AI (Ollama): set Base URL (default
http://127.0.0.1:11434) and choose a Model (e.g.,llama3.2,mistral,qwen2.5). - For cloud providers: enter your API key and select a model.
- Customize the system prompt to tune brainy's writing style.
Usage:
- Click the brainy button (sparkles icon) in the sidebar to open the chat panel.
- Ask brainy to perform actions like "create a new note about project ideas" or "search for notes about recipes".
- brainy will execute tools automatically and confirm completed actions.
- Global Hotkey (Windows): default
Alt+Shift+Btoggles the capture modal. - Custom Protocol (Windows): open
brainbox://capture?url={URL}&title={TITLE}to send the current page to brainbox. The app registers the protocol under the current user. - Bookmarklet: drag the localhost bookmarklet from Settings → Capture. With selected text it opens a sourced note; without a selection it opens the existing page-link capture.
examples/bookmarklet-direct.jscontains the same bookmarklet code. - Bridge Page:
examples/brainbox-bridge.htmlis a small page that redirects to the brainbox protocol; you can host/use it to create links that trigger the app.
- Storage: database file is created at the OS "local app data" directory as
brainbox.sqlite.- Windows:
%LOCALAPPDATA%(e.g.,C:\\Users\\<you>\\AppData\\Local). - macOS:
~/Library/Application Support.
- Windows:
- Search: decrypted tokens live only in RAM while the app is running; legacy on-disk search indexes are removed at startup.
- Encryption: uses XChaCha20‑Poly1305 (32‑byte key) for item content and vault passwords.
- ✅ Security Update (v0.0.1): Encryption keys are now properly derived from user passwords using PBKDF2 with 100,000 iterations and vault-specific salts.
- Keys are derived on-demand and cached in memory during the session for performance.
- Keys are automatically cleared when vaults are closed or the app exits.
- New sync exports require a sync file passphrase and wrap vault names, item titles, content, summaries, covers, and device name in an encrypted envelope. Legacy plaintext sync files can still be imported for migration.
- Manual
.brainboxbackups also require a passphrase and are encrypted before leaving the app; legacy JSON exports remain importable for migration. - Standalone capture files are not exported by encrypted sync because they sit outside the sync JSON envelope.
⚠️ Educational Purpose: This implementation demonstrates proper cryptographic practices but is intended for learning. For production use with sensitive data, additional security measures would be required:- Hardware-backed key storage (TPM, Secure Enclave)
- Biometric authentication
- Key rotation mechanisms
- Professional security audit
- Secure key backup and recovery
- AI can run locally via Ollama or LM Studio for fully offline operation. Cloud providers (OpenAI, Anthropic, Google, OpenRouter) are also supported. Leaving AI unconfigured keeps brainbox fully offline.
| Platform | Status | Notes |
|---|---|---|
| Windows | Full Support | Global hotkey, protocol handler |
| macOS | Core Features | App runs, hotkey/protocol pending |
brainbox/
├─ src/ # React app (UI, components, contexts, utils)
│ ├─ components/ # UI components (BrainyChat, Sidebar, etc.)
│ └─ utils/ai/ # AI service layer
│ ├─ service.ts # Unified AI provider management
│ ├─ types.ts # TypeScript interfaces
│ ├─ tools.ts # Tool definitions for brainy
│ ├─ toolExecutor.ts # Maps tools to Tauri commands
│ ├─ agentLoop.ts # Hybrid native/prompt-based agent loop
│ └─ providers/ # Provider implementations (Ollama, OpenAI, etc.)
├─ src-tauri/ # Tauri (Rust) backend, commands, tray, protocol
│ ├─ src/lib.rs # Main Tauri builder and command registration
│ ├─ src/sync_commands.rs # Sync command wrappers
│ ├─ src/paths.rs # App data path helpers
│ ├─ src/vault.rs # SQLite models for vaults and items
│ └─ src/search.rs # Tantivy index and search service
├─ styles/ # Design tokens, globals, themes
├─ public/ # Static assets
├─ examples/
│ ├─ bookmarklet-direct.js # Localhost bookmarklet for links and selected text
│ └─ brainbox-bridge.html # Protocol bridge page
dev: run Vite locally.tauri dev: run desktop app in dev mode (Vite + Tauri).build: build frontend assets.tauri build: produce desktop bundles.
mainbranch: Validated integration branch; it does not publish releasesdevbranch: Active development (default working branch)
- Work on features in the
devbranch - Test thoroughly before merging to
main - Merge
dev→mainand confirm CI passes - Create a matching
vMAJOR.MINOR.PATCHtag to run the protected release workflow
The release workflow validates first, packages an unsigned EVB portable executable and a notarized DMG, verifies checksums, then publishes a complete draft.
Platform Support:
- Global hotkey: Windows only (macOS)
- Protocol handler: Windows only (macOS)
- Proper key management and encryption UX.
- Cross‑platform global hotkey and protocol support.
- Richer previews and content extraction.
- Import/export and backup/sync options.
- Plugin API for custom capture/processing flows.
MIT — see LICENSE for details.