Install & User Guide

Everything you need to install, run, and get real work out of Cache Vault — the local-first Windows clipboard vault.

Download & verify release

Download the packaged Windows build from the latest GitHub Release. After downloading the release zip, compute its SHA256 hash in PowerShell:

Get-FileHash .\CacheVault-*.zip -Algorithm SHA256

Compare the reported hash against SHA256SUMS.txt from the same release. If the values match, the archive matches the published release artifact.

Install & run

To run from source (a Python checkout):

# from the repo root
python -m venv .venv
.\.venv\Scripts\Activate.ps1
pip install -r requirements.txt
python app.py

Headless sanity check (no window — used by CI):

python app.py --selftest

Build a standalone .exe

pwsh packaging\build_exe.ps1     # -> dist\CacheVault.exe (one-file, windowed)

The build bundles CustomTkinter's theme assets. Verify the build headlessly with dist\CacheVault.exe --selftest. The packaged exe also stamps Windows file/product metadata from the source version; verify it with python tools\verify_exe_metadata.py --exe dist\CacheVault.exe.

First run

Cache Vault runs as a tray app. The teal tray icon shows the app is running. Closing the window hides it to the tray; use the tray menu's Quit action to stop capture, remove the tray icon, and exit cleanly.

The single tray menu offers: Open Cache Vault · Pause Capture · Resume Capture · Clear Sensitive Clips · Quit.

The global quick-paste hotkey defaults to Ctrl+Shift+V (Win+V is reserved by Windows).

Start with Windows

Settings → Start Cache Vault with Windows adds a per-user HKCU\…\CurrentVersion\Run entry (no admin rights, fully reversible). For a dev checkout it launches pythonw app.py; for a packaged build it launches the exe directly.

Organize & export

Right-click any clip for Copy Again, Add/Remove Favorites, Move to Collection…, Export / Save As…, Open / Reveal in Explorer (local path clips only), and Remove from History.

Sidebar sections: All Clips, Favorites, Collections (virtual app folders — one DB, not separate vaults), and Recently Removed (Restore or Permanently Remove).

Export a single clip as .txt / .md / .html / .json, or a whole view / collection as an organized folder or zip (index.html, manifest.json as Proof Manifest, stamped_receipt.txt, clips/). Path clips export a reference + metadata only by default; real files are copied into files/ only if you tick Include file copies, and originals are never moved or deleted.

Search syntax

type:link github      type:code python      source:cursor
sensitive:true        pinned:true           <free text>

Unknown key:value tokens fall back to free-text search. Search is substring (LIKE) matching, not a full-text index — fine for MVP volumes.

Smart filters

Rule-based, no AI. Each clip gets one primary type plus tags:

• Links — http(s):// and conservative bare domains.
• Files / Paths — C:\…, D:\…, UNC \\server\share, quoted paths.
• Code — keywords / braces / multi-line indentation heuristics.
• Commands — leading git, python, npm, winget, docker, … (a git clone https://… is a command, not a link).
• Emails / Phone numbers — conservative regex to avoid over-detecting.
• Sensitive — API keys, tokens, JWTs, private keys, credit-card numbers (Luhn-checked), recovery/one-time codes, and high-entropy secrets.

Sensitive handling

Sensitive clips get a masked preview, an explicit Reveal action, an auto-expiry timer (default ON, 10 minutes), and a one-click Clear Sensitive Clips. On expiry the secret content is scrubbed from the database; the row survives only as an Expired entry and an event-log line — the event log never stores the secret. Clipboard contents are never written to logs or printed to the console.

Quick paste (global hotkey)

Press Ctrl+Shift+V anywhere to pop up a quick picker of your most recent clips, no matter which app is focused:

• ↑ / ↓ move the selection, 1–9 jump straight to a row
• Enter pastes the highlighted clip, Esc cancels

Choosing a clip copies it and — if Auto-paste is on (default) — restores focus to the app you were in and sends Ctrl+V for you. The hotkey and auto-paste behaviour are configurable in Settings; the hotkey re-registers live when you change it.

Where data lives

Local app data stays under %LOCALAPPDATA%\CacheVault\:

Everything lives in a local SQLite database. No cloud account, no subscription, no ads, no telemetry. The optional LAN bridge is off by default and never connects to the internet.

Honest scope & limitations (v0.1.4)

Implemented: text clipboard capture, smart filters, search, pin/keep/expire/delete, duplicate collapse, sensitive masking + auto-expiry, tray, global quick-paste hotkey (Ctrl+Shift+V) with auto-paste, local event log.

Not implemented (by design, for this MVP): cloud sync, accounts, browser extension, mobile app, OCR, AI classification, remote backup, image/file capture, payment/licensing.

Tradeoffs we're honest about

• Search is substring (LIKE) matching, not a full-text index. An FTS index can come later.
• Clip content is stored as plain text in the local database. The schema isolates content so encryption can be added later without migration. We do not claim encryption today.
• Clipboard monitoring prefers event-based capture via AddClipboardFormatListener (pywin32). If pywin32 is unavailable it falls back to throttled polling (default 800ms).
• Source app/window detection is best-effort and degrades to "unknown" without crashing when it can't be determined.