Get it running.
Installation, first-run behaviour, scanning and search problems, licensing status, and how to reach a person.
Installation
ClipVault is currently a developer preview built from the repository — there is no signed installer yet — see early access for where the build stands and how to get one. Once you have a checkout, the short version is:
xcode-select --install # swiftc, for the window wrapper brew install ffmpeg exiftool # needed for real scans only python3.11 -m venv .venv .venv/bin/pip install -r backend/requirements.txt ./native/build-app.sh # produces ClipVault.app
Requirements: macOS 12 Monterey or newer, Python 3.11 or 3.12, Node 20+. On Intel Macs use Python 3.11 specifically — PyTorch, which visual search needs, has no wheels for newer versions there.
First run
- Sample mode is available immediately, with no account and no trial.
- macOS asks for disk access only when you choose a media location.
- The index and cache are written to ~/.clipvault/, separately from your media.
- Your originals are opened read-only and are never modified.
Scanning your own media
Use the Scan Queue screen to connect a folder or drive, then pick a mode:
- Fast — paths, sizes and dates only. You get a browsable library immediately.
- Standard — fast, plus real metadata (ffprobe for video; ExifTool for photos, RAW and camera/lens on video) and derivatives: a 512-pixel thumbnail per asset and 5–12 keyframes per video. RAW previews come from the JPEG the camera embedded, so no RAW decode runs.
- Deep — currently the same work as standard. Scene detection, quality scoring and duplicate detection are not implemented yet, and we would rather say so than imply a mode does more than it does.
Rescans are idempotent: existing assets are refreshed and existing derivatives are skipped, so re-running a scan is safe and cheap.
Search
Text search works as soon as assets are indexed — it matches filenames, paths, summaries and tags. Visual search needs two extra things: the AI dependencies (pip install torch open_clip_torch) and an AI indexing pass over the library. Until embeddings exist, the app says so rather than returning nothing silently.
Drives and permissions
macOS gates access to removable volumes and to some user folders. If ClipVault cannot see a drive, open System Settings → Privacy & Security → Files and Folders — and for a fully mounted archive drive, Full Disk Access — allow ClipVault, then relaunch it. That access is only ever used to read.
If a drive is unmounted after indexing, its assets stay in the library with their metadata, previews and keyframes. They simply cannot be opened at source until the drive is back.
Licensing
There is no licensing, trial or activation system in the current build. Nothing is gated, nothing expires, and there is no key to enter or transfer. If a page or a person tells you otherwise about this preview, they are wrong.
The model we have committed to for 1.0 — and the constraints licensing will be built under — is on the pricing page. When it ships, this section will carry real error messages and real remedies.
Troubleshooting
A known bug with a known fix. An app launched from Finder inherits a PATH without Homebrew or nvm, so the launcher could not find npm and stopped before starting the backend. Current builds resolve node and npm themselves and fall back to the previously built interface rather than failing. Rebuild with ./native/build-app.sh.
Expected — the preview is compiled on your machine and carries no Developer ID signature or notarization ticket. Open System Settings → Privacy & Security, find the blocked-app message and choose Open Anyway. Only do this for a build you produced yourself.
FFmpeg and ExifTool are missing, or the running process cannot see them. brew install ffmpeg exiftool, then quit and relaunch ClipVault before rescanning — a process started before the tool-path fix cannot find Homebrew binaries and will report success while producing nothing.
Use the Photos screen. It runs the photo preview pass on its own, scoped to a folder if you want, with live progress — photos are the cheap half of the work (a RAW preview is the JPEG the camera already embedded) and behind a mixed pass they would queue behind video frame-seeks.
Install the AI dependencies (pip install torch open_clip_torch) and run an AI indexing pass. Embeddings are computed from the small derivatives, so the pass needs previews and keyframes to exist first.
That is the byte budget working as designed, not an error. Remote scans prefer a provider thumbnail, then a ranged read of just the header needed; anything that would cost more than the budget is marked deferred rather than pulled silently. Raise the budget or run a deeper pass on a narrower prefix.
Scope the view to a connected folder rather than the whole library, and let the preview pass finish — grids are fastest once thumbnails exist. For reference, a development library of 17,488 assets runs on a 168 MB index with a 500 MB preview cache.
Uninstalling
- Reset the library: delete ~/.clipvault/index.sqlite.
- Clear derivatives: delete ~/.clipvault/cache/.
- Remove everything: delete ClipVault.app and ~/.clipvault/; remove any cloud-source item from Keychain Access.
Your original media is never affected by any of these.
Contact
ClipVault support runs through DGTL. When you get in touch, include:
- Your macOS version, and whether the Mac is Intel or Apple Silicon.
- The ClipVault version (see the release manifest for the current one).
- What you were doing, and what happened instead.
- The last lines of ~/.clipvault/logs/.