Wakii's Electron process model

Every Electron app runs at least three processes in parallel: a main process that holds OS privileges, a renderer that draws the UI, and a preload script standing between them. Most Electron security stories start from the same mistake: the renderer is given too much power. Wakii runs the other direction — the renderer lives in a sandbox with no Node.js, privileges are consolidated in the main process, and the path between the two sides is a typed contract you can read. This post walks each boundary with the actual code from the public repo wakii-dev/wakii; every path cited below points to a real file you can open and check line by line.

TL;DR:

The main process holds every OS privilege — files, shell, keychain, child processes; the renderer is just a sandboxed web page.
The main window is created with sandbox: true; guest windows (embedded web content) spell out the full contextIsolation, nodeIntegration, sandbox set.
The renderer never imports electron — it calls window.api, an object the preload exposes via contextBridge, made of 79 bridges split by domain.
Both sides of the IPC share one set of TypeScript types in src/shared, with the preload side pinned by satisfies PreloadApi.

Three processes, three levels of privilege

The main process is a real Node.js program: it reads and writes files, spawns child processes, talks to the keychain, opens sockets, creates windows. The renderer is Chromium — in privilege terms it is no more than a sandboxed browser tab: what it can touch on the system is close to nothing. The preload is special: a script that runs inside the renderer process, before the web page, with exactly one narrow privilege — access to a few Electron APIs so it can translate, but still no Node.js.

Calls move in one controlled direction. UI code never opens a file by itself; it calls a function on window.api, the preload turns that into an IPC message, the main process receives it, decides, and resolves a Promise back.

        ┌───────────────────────────────────────────────┐
        │                PROCESS MAIN                   │
        │  Full Node.js: files · shell ·                │
        │  keychain · child processes · network         │
        │  ipcMain.handle("domain:action", ...)         │
        └───────────────────▲───────────────────────────┘
                            │  IPC (invoke / reply)
┌───────────────────────────┴───────────────────────────┐
│                PROCESS RENDERER                       │
│  Chromium sandbox — no Node.js                        │
│                                                       │
│   UI code ──calls──▶ window.api ──▶ preload (translates)
│              window.api = contextBridge               │
└───────────────────────────────────────────────────────┘

Diagram summarizes src/main/index.ts (main process) and src/preload/index.ts (exposing window.api) — public repo wakii-dev/wakii, captured 2026-09-08.

The most important part of the diagram is the arrow’s direction: from the renderer there is no path to OS resources — files, shell, keychain — that does not pass through a handler the main process registered itself. A web page in the renderer can fetch from the internet like any web page, but opening a file on your machine requires asking.

The main window: security flags right where the window is created

src/main/window/createMainWindow.ts is where everything starts. The webPreferences of the main window, verbatim:

// src/main/window/createMainWindow.ts
webPreferences: {
  preload: join(__dirname, '../preload/index.js'),
  sandbox: true,
  webviewTag: true,
  // Why an argument and not an IPC read: this is the window whose webviews host browser guests,
  // and it has to know that before it interprets its first session snapshot — earlier than any
  // handler registration it could wait on.
  additionalArguments: [formatBrowserClientHostIdArgument(getBrowserClientHostId())]
}