How Velnode Browser Works

Velnode Browser  ·  a product of Dignity New Zealand Limited

_{Product  |  Version 1.6  |  Last updated 2026-07-03}

How Velnode Browser Works

Document type: Product Owner: Dignity New Zealand Limited Applies to: Velnode Browser v2.3.2-beta.1 and later Last updated: 2026-07-03 Document version: 1.6 Status: Approved

This document is the plain-language story of what Velnode Browser is doing under the hood. It is meant for users who want more depth than the Features list but who do not need the engineering detail of the Architecture Overview.

Velnode Browser is a product of Dignity New Zealand Limited.

1. The big picture

Velnode Browser is an Electron application. Electron is a runtime that lets a single codebase ship as a desktop app on Windows, macOS, and Linux. Velnode's first public beta ships for Windows 10/11 (64-bit); macOS and Linux builds are planned. Inside an Electron app there are two kinds of processes:

• A single main process that owns the operating-system handles, the network, and any privileged work.
• One or more renderer processes, each one a sandboxed Chromium window or tab, restricted to the web platform.

In a normal browser the renderer is "the page you see". In Velnode the renderer is the user interface and the tab content, and the main process is where the trust lives. Every decision that matters — should this AI call go out at all, should this URL be allowed in Kids Mode, should this plugin be granted disk access — is taken in the main process, not the renderer.

If you only remember one sentence from this document, remember this one: trust is in the main process; the renderer never decides on its own.

2. What happens when you open the app

1. The Electron main process boots. It reads package.json, applies the Velnode defaults (nodeIntegration: false, contextIsolation: true, sandbox: true), and registers the IPC allow-list defined in preload.js.
2. The main process opens data/settings.json to learn your preferences, including whether Kids Mode is on, whether Local-Only mode is on, and which plugins you have explicitly enabled.
3. The first renderer window loads index.html. That is the Velnode user interface.
4. The renderer asks the main process for everything it needs to draw the UI: your bookmarks, your timeline, your pinned commands, your sidebar state. None of that information is fetched from a server.
5. The window appears, and the cursor is parked in the Command + Context bar.

The whole sequence is designed to finish in under two seconds on a five-year-old mid-range laptop. That target is treated as an architectural invariant; we do not let new features regress it without explicit waiver.

3. What happens when you load a web page

When you type a URL or click a link, the renderer asks the main process to navigate the active tab.

• The main process consults the navigation guardrails. External schemes (mailto:, tel:, custom protocol handlers) are subject to explicit review; the unknown ones are denied by default.
• If Kids Mode is on and the URL is not on the allow-list, the main process redirects the tab to blocked.html and leaves a timeline entry.
• Otherwise the tab loads the URL through ordinary Chromium. From here Velnode behaves like any other browser: cookies are handled by Chromium, certificates are validated by Chromium, and content security policies are enforced by Chromium.

Velnode does not interpose itself in the page's network traffic. We do not run a man-in-the-middle proxy. We do not log the body of pages you load. We do not relay your traffic through any Dignity New Zealand Limited server.

4. What happens when you talk to Vee

Vee is the single AI identity in Velnode. Whether you summon Vee by typing in the Command + Context bar, by clicking the Vee button, by speaking the wake-word (opt-in), or by accepting a suggestion strip on a page, the flow is the same.

1. The renderer collects what Vee needs: your prompt, the active-tab context if the prompt depends on it, and a window of recent conversation turns.
2. The renderer hands the request to the AI Gateway in the main process over the IPC allow-list.
3. The Gateway runs the request through the policy layer:
   • Kids Mode check (if on, forces Local-Only path).
   • Local-Only check (if on, refuses to call any cloud provider regardless of configured API keys).
   • Token-cap check (refuses prompts that would breach the configured budget at a cloud provider).
4. The Gateway selects a provider. Cloud providers are called with your own API key from main-process storage. The optional local LLM brain (Phase 12 H — downloaded only after you opt in) is called by direct in-process binding through node-llama-cpp.
5. The Gateway returns the response to the renderer.
6. The renderer renders the response in the surface that asked for it — a summary card, the modal answer panel, a voice reply, or a suggestion strip.
7. The exchange is appended to data/timeline.json. EchoVee rebuilds its semantic memory from the timeline so Vee can remember the conversation later.

A subtle point worth emphasising: because the policy layer is in the main process and the renderer cannot reach the network on its own, a malicious page cannot cause Vee to send a prompt that bypasses your settings. Even a misbehaving official plugin cannot. The policy decision is taken in the place that owns the network.

5. How memory works

Velnode's memory is two layers:

• Timeline. data/timeline.json is the append-only ledger. Every event — a tab opened, a navigation, a Vee prompt and its response, a note created, a bookmark added — is a line in this file. The file is the canonical record.
• Semantic memory. data/semantic-memory.json is rebuilt deterministically from the timeline. It is the working memory Vee uses to recall "what were we doing yesterday morning". You can throw it away at any time; Velnode will rebuild it on the next launch from the timeline.

Append-only is a deliberate choice. It means a bug, a crash, or a malicious plugin cannot rewrite history. The file is your record of your own activity on your own device.

If you want to forget — delete timeline.json. Velnode will start a fresh ledger on the next launch.

6. How bookmarks work

Velnode's Bookmark Manager uses a flat-preserving data model. Every saved bookmark lives in a single flat list in data/bookmarks.json, which keeps all existing features that read bookmarks working without modification. Folder structure — which bookmark belongs to which folder, and in what order folders appear — is stored separately in data/bookmark-tree.json.

When you save a bookmark (via the ★ in the address bar or Ctrl+D), the main process writes to both files: the flat list gets a new entry, and the tree file records its folder placement. The two files always stay in step.

Favicons displayed next to bookmarks come from Velnode's own local favicon cache. Velnode does not call an external favicon service; if a favicon is not in the cache, the entry displays a plain icon instead.

The Bookmark Manager ships four surfaces over this single data model: a Favorites bar (toggleable strip under the toolbar), a Favorites flyout (right-side panel), a ★ popover in the address bar, and a full two-pane manager at velora://bookmarks. All four read and write the same files.

Import and Export use the standard Netscape bookmark HTML format that Chrome, Edge, and Firefox all recognise. Importing rewrites the tree with the imported structure; exporting produces a single HTML file you can open in or import into any compatible browser.

7. How the optional Velnode Account works

You can use Velnode without ever creating an account. If you do create one, here is what happens.

Sign-up. Velnode generates two random values from your password: an authentication hash (sent to the Account Server to prove you know the password) and a Key Encryption Key (KEK), which stays on your device and is never sent anywhere. A random 32-byte account data key is generated locally, wrapped by the KEK, and only the opaque encrypted blob reaches the Account Server. The server never sees your password, your KEK, or your data key.

Subsequent launches on the same device. The data key is cached in the operating system's secure storage (the same mechanism the vault uses). Velnode reads it silently on launch; you do not retype your password.

New device. You sign in with your email and password. Velnode runs the same KDF to re-derive the KEK, fetches the opaque blob from the Account Server, and unwraps the data key. No extra codes are needed.

Forgot password. A password-reset link restores your ability to log in. Because the new password produces a different KEK, the existing encrypted blobs cannot be unwrapped automatically. The Account Server retains the old blobs — it never deletes them. You then enter your 24-word Recovery Kit, which was generated at sign-up and held only by you: Velnode uses it to unwrap the data key and re-wrap it under the new KEK.

If you have lost both your password and your Recovery Kit: the password reset restores your login, but the previously encrypted data is unrecoverable. This is the honest, unavoidable consequence of true end-to-end encryption, and it is stated plainly during sign-up.

The vault is separate. Signing in does not unlock the vault. Vault secrets open only with your vault master passphrase. The vault travels as an opaque encrypted payload when sync is active; the account data key is never used to read vault contents.

Signed-out experience. When you sign out — or when you never sign in — Velnode works exactly as it always has. Data lives locally in data/*.json. Nothing changes for signed-out users.

7a. How account sync works

Signing in to a Velnode Account turns sync on automatically. There is no separate sync passphrase. Sync is optional and additive; your local data/*.json files remain the single source of truth.

What syncs. Seven categories sync independently. Each has its own toggle in Settings → Sync, and all are on by default:

Encryption. Each collection's changes are encrypted with the account's random 32-byte data key (AES-256-GCM, with authenticated additional data binding the account ID and collection name), then stored as opaque ciphertext on Velnode's Cloudflare Worker and D1 backend. Velnode cannot read your sync data — the server sees only ciphertext, record sizes, and timestamps.

Persistent sign-in. Once signed in you stay signed in across restarts. A quiet token-rotation schedule keeps the session alive for active users. An opt-in "Always ask me to sign in on launch" toggle (off by default) disables this for users who prefer to re-enter their password on each launch. If a session expires or is revoked, sync pauses and a prompt appears — local data is never deleted as a result of a session event.

Per-category toggles. Turning a category off stops future sync for that category. Data already synced to the server is not deleted; it remains available if you turn the category back on or sign in on another device.

Deletions across devices. Velnode keeps a local tombstone log that records deletions (bookmarks, pinned commands, workspaces, notes) for up to 180 days, with a 1 000-entry cap per collection. Tombstones are embedded in compaction snapshots, so a device coming back online after a compaction still receives outstanding deletions. The only remaining edge case is a device that has been offline for longer than 180 days — it may not receive deletions made before the window opened. For everyday use, deletions propagate reliably across devices.

8. How privacy is enforced

Five architectural decisions do most of the work:

1. Single gateway. All AI calls go through one place. We can audit it, sign it, and reason about it.
2. Main-process policy. Kids Mode and Local-Only mode are enforced where the network is, not where the user interface is. A page cannot ask a renderer to call a cloud provider.
3. File-backed state. Your data lives in data/*.json on your device. The account is an additive opt-in layer; it does not replace local files.
4. Zero-knowledge data layer. If you use an account, the Account Server stores only ciphertext it cannot read. Your data key is derived from your password on your device and never transmitted in usable form. When sync is active, each collection's ciphertext is bound to both your account ID and the collection name — a bookmark blob cannot be misread as a history blob, and a blob from one account cannot be decrypted by another.
5. Fingerprint protection. Browser fingerprinting lets a third-party website identify your browser without cookies by combining signals like canvas rendering, GPU details, and font availability. Velnode ships a farble engine that injects per-origin noise into canvas and WebGL read-backs, cohorts the GPU identity strings, cohorts the font-enumeration APIs, and presents a common Chrome identity (User-Agent, client hints) on guest pages. The result is that the rendered-image fingerprint is unlinkable across sessions. Incognito and Tor windows are always protected; in normal windows you enable it via Settings → Privacy → Fingerprint Protection. Honest caveat: WebGL capability parameters (extension list, max texture size) and metric-based font measurement are not spoofed in this release, so a partial fingerprint is still possible for a determined adversary — this is consistent with what privacy-focused browsers ship today.

See the Privacy Policy for the legal framing of the same set of choices.

9. How resource discipline is enforced

Velnode is designed to compete on the laptops most people actually own. Velnode's resource-discipline rules are the engineering version of a brand promise:

• Lazy loading. Plugins, the optional local LLM, and the wake-word model never run at boot. They load when first invoked.
• Per-plugin RAM budgets. The Modular Runtime Core enforces a memory ceiling per plugin and cold-restarts plugins that blow past it.
• Visible cost. Settings → Velnode System Health shows live RAM and disk usage so you can see what each feature actually costs.

The promise we make to users is simple: Velnode is lightweight by default. Local AI, wake-word, and heavy plugins are opt-in downloads — you choose what to add. Your laptop's resources are yours.

10. How updates work

We publish releases under semantic versioning. The version of Velnode you are running is shown in the title bar and is also written into package.json in the installer. Since v2.3.3-beta.13 the Windows installer is digitally signed by DIGNITY NEWZEALAND LIMITED, our registered company. When a new release exists, Velnode shows you a notice; the update downloads inside the app, every byte is verified against the release feed's published checksum before anything runs, and it installs only when you click Restart to apply — Velnode never silently replaces itself.

A material change to behaviour — a new permission, a new outbound call, a new policy default — is always called out in the release notes for the version that introduces it. Architecture flags in canon_manifest.json cannot regress: a release that flipped, say, ai_local_only_enforced_main_level to false would fail our own pre-release checks.

11. Where to read next

• Features — the full inventory.
• Architecture Overview — the engineering story for developers.
• Vee Capabilities — what Vee can and cannot do, and how to ask well.
• Privacy Policy — the legal version of §6.
• Velnode Account — account setup, sync categories, persistent sign-in, and Recovery Kit.

Document maintained by Dignity New Zealand Limited. Questions: [email protected].