Vev documentation — architecture, building on every platform, and configuration

Architecture Building from source Subsystems Configuration reference Retraining the AI Threat model Contributing

Architecture

Vev is a Tauri 2 (Rust) shell that embeds Chromium Embedded Framework (CEF) as the real multi-process rendering engine. The shell draws the chrome — tab strip, omnibox, the Dynamic Island, and the internal vev:// pages — in a lightweight system webview. Each tab is a separate CEF browser with its own renderer process, so one page crashing can't take down the others.

A Rust workspace provides the substance: privacy, security, blocking, storage, Tor, downloads, and the on-device AI. A second small binary, vev_helper, is the entry point for CEF's renderer and service-worker processes; it installs the fingerprint spoof into every JavaScript context.

Building from source

Prerequisites (all platforms): Rust stable, the CEF binary distribution, and the bundle-cef-app helper from a cef-rs checkout. The build is orchestrated by a Makefile.

make run        # build + bundle + launch
make test       # cargo test across the workspace
make bundle     # assemble the app bundle without launching
make autotest   # in-app runtime self-test suite
make train      # retrain the Huma phishing model (ONNX)
make clean      # kill stale processes and clear bundle state

macOS

Verified on Apple Silicon. Install the CEF distribution to ~/.local/share/cef, then make run. Do not re-sign the bundle with codesign --deep — it corrupts CEF's nested signatures; rebuild with make bundle, which signs correctly.

Windows

Use the Windows CEF distribution and the MSVC Rust toolchain, then make dist-win (or the equivalent bundle-cef-app invocation). Windows uses the same Rust workspace; the window-embedding layer is being brought up to parity with macOS.

Linux

Use the Linux CEF distribution and the standard toolchain, then make dist-linux. As on Windows, the workspace and engine are shared; platform window embedding is in progress.

Subsystems

Each lives in its own crate under crates/:

huma — the on-device AI: guard (URL model), content (page-content phishing), adapt (self-adaptation), model (ONNX via tract), read (summaries), predict (prefetch).
vev-fingerprint — the fixed reference profile and the spoof script injected into every context.
vev-network — DoH policy, HTTPS-upgrade rules, resolver allowlist.
vev-blocklist — adblock-rust network blocking, cosmetic filtering, the live threat feed, and the community phishing feed.
vev-storage — the AES-256-GCM encrypted vault for history, bookmarks, and passwords.
vev-tor — embedded Arti and its local SOCKS bridge.
vev-download / vev-torrent — the segmented downloader and the librqbit torrent engine.

Configuration reference

User data and config live in your OS app-data directory (on macOS, ~/Library/Application Support/com.vev.browser). Key files:

config.json — search_engine, home_url, huma_guard (bool), community_feed_url, community_reporting (bool, default false), report_endpoint.
network.json — resolver allowlist and DoH overrides.
vault.enc — the encrypted store; master.key — the local key (0600).
huma-adapt.json — your personal Guard adapter; huma-nav.json — the prefetch model.
extensions/ — unpacked extensions; blocklists/ — optional filter lists.

Retraining the AI

The phishing model is trained offline and bundled as a ~1 KB ONNX file. To retrain, run make train: it generates a labelled dataset, extracts features with the same Rust extractor the browser uses at inference (guaranteeing train/serve parity), trains a small MLP with numpy, and exports model.onnx. The training scripts live in scripts/train_guard/.

Threat model

Vev protects against: cross-site tracking via fingerprinting, WebRTC IP leaks, plaintext DNS, third-party cookies, network-level ads and trackers, phishing (URL and content), and local data theft (the vault is encrypted at rest).

Vev does not fully protect against: a few remaining fingerprint surfaces (CSS-media screen size, local font enumeration, some headless signals), and per-tab Tor (only browser-wide Tor is available with the embedded engine). These are documented deliberately.

Contributing

Vev is open source on GitHub. Each subsystem is a self-contained crate with unit tests; the in-app make autotest suite exercises the real command layer at runtime. Runtime verification — reproduction steps, expected vs. observed — is preferred over compilation alone before a feature is considered done.

How Vev is built