Vayu System Architecture¶
Vayu uses a Sidecar Architecture that decouples the user interface from the execution engine. This separation allows each component to be optimized for its specific purpose:
- The Manager (Electron/React): Optimized for user experience
- The Engine (C++): Optimized for raw performance
High-Level Architecture¶
┌─────────────────────────────────────────────────────────────────────┐
│ Vayu Application │
├─────────────────────────────────────────────────────────────────────┤
│ │
│ ┌─────────────────────────┐ ┌─────────────────────────────┐ │
│ │ THE MANAGER │ │ THE ENGINE │ │
│ │ (Electron + React) │ │ (C++) │ │
│ │ │ │ │ │
│ │ ┌───────────────────┐ │ │ ┌───────────────────────┐ │
│ │ │ Request Builder │ │ │ │ HTTP Server │ │
│ │ │ Response Viewer │ │ HTTP │ │ (cpp-httplib) │ │
│ │ │ Dashboard │◄─┼──────┼─►│ Port: 9876 │ │
│ │ │ Collections │ │ │ └───────────────────────┘ │ │
│ │ └───────────────────┘ │ │ │ │ │
│ │ │ │ │ ▼ │ │
│ │ │ │ │ ┌───────────────────────┐ │
│ │ ▼ │ │ │ Worker Threads │ │
│ │ ┌───────────────────┐ │ │ │ ┌─────┐ ┌─────┐ │ │
│ │ │ Sidecar Manager │ │ │ │ │ W1 │ │ W2 │ ... │ │
│ │ │ (spawn/kill) │ │ │ │ └──┬──┘ └──┬──┘ │ │
│ │ └───────────────────┘ │ │ └─────┼──────┼─────────┘ │
│ │ │ │ │ │ │
│ └─────────────────────────┘ │ ▼ ▼ │
│ │ ┌───────────────────────┐ │
│ │ │ Event Loop │ │
│ │ │ (curl_multi) │ │
│ │ └───────────────────────┘ │
│ │ │ │
│ │ ▼ │
│ │ ┌───────────────────────┐ │
│ │ │ Script Engine │ │
│ │ │ (QuickJS) │ │
│ │ └───────────────────────┘ │
│ │ │ │
│ │ ▼ │
│ │ ┌───────────────────────┐ │
│ │ │ SQLite Database │ │
│ │ │ (Collections, Runs) │ │
│ │ └───────────────────────┘ │
│ │ │
│ └─────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────────┘
The Manager (Electron + React)¶
The Manager is the "face" of Vayu-a standard Electron application that provides the graphical interface.
Key Responsibilities: - Request building and editing - Collection management - Environment variable management - Real-time load test dashboard - Run history viewing
Technology Stack:
- Electron 44: Desktop app framework
- React 19: UI framework
- TypeScript: Type safety - 7 compiles and checks, 5.9 stays installed for the typescript-eslint parser (see app building)
- Zustand: UI state management
- TanStack Query: Server state and caching
- Radix UI: Accessible component primitives
- Tailwind CSS: Styling
See App Architecture for detailed information.
The Engine (C++)¶
The Engine is the "muscle"-a headless daemon optimized for maximum I/O throughput.
Key Responsibilities: - HTTP request execution (libcurl) - Load test orchestration - Script execution (QuickJS) - Metrics collection - Data persistence (SQLite)
Technology Stack: - C++23: Core language - cpp-httplib: HTTP server - libcurl: HTTP client (HTTP/1.1, HTTP/2 via nghttp2 - HTTP/3 is not supported) - QuickJS: JavaScript engine for scripts - SQLite: Embedded database - sqlite_orm: C++ ORM
See Engine Architecture for detailed information.
Communication Protocol¶
The Manager communicates with the Engine via a localhost HTTP API on port 9876. If another program already holds that port, the Manager runs the engine on a fallback port instead and tells the renderer which (see Ownership model); the Dock's engine status shows the address.
Request/Response Flow¶
Manager Engine
│ │
│ POST /execute │
│ {method, url, headers, body} │
├───────────────────────────────────►│
│ │
│ 200 OK │
│ {status, headers, body, timing} │
│◄───────────────────────────────────┤
Change Feed¶
The engine's stored rows have more writers than the Manager: the stdio MCP CLI,
vayu-cli, a script against the API, a second window. So the Manager holds one
Server-Sent Events stream for its whole life, GET /changes, on which the
engine publishes one event per committed write of a collection, a request, an
example, an environment, the globals or a trash entry, whoever made it (issue
3420). The event names the row and the operation and carries no row data:¶
the Manager refetches what it names through its query layer, so a row still reaches the UI by exactly one path.
Manager Engine
│ │
│ POST /changes/subscriptions │
├───────────────────────────────────►│
│ {subscription} │
│◄───────────────────────────────────┤
│ GET /changes?subscription=ID │
│ [&lastEventId=N] │
├───────────────────────────────────►│
│ │
│ event: ready (or reset) │
│◄───────────────────────────────────┤
│ │
│ event: change │
│ data: {kind, id, op, ...} │
│◄───────────────────────────────────┤
│ (repeated) │
A stream opens on a single-use subscription id, which the Manager asks for with a
POST before every connection, a reconnect included. A dropped stream reconnects
from the last id it saw and the engine replays what was missed; a resume the engine can no longer cover (too far behind, or an id
from before an engine restart) opens with reset instead, and the Manager
refetches everything the feed describes. The stream is open only while the
health poll says the engine is connected. The renderer side is described in
State management, and the route in the
API reference.
Load Test Flow¶
Manager Engine
│ │
│ POST /runs │
│ {request, mode, duration, ...} │
├───────────────────────────────────►│
│ │
│ 200 OK {runId} │
│◄───────────────────────────────────┤
│ │
│ GET /runs/{runId}/live (SSE) │
├───────────────────────────────────►│
│ │
│ event: metrics │
│ data: {rps, latency, ...} │
│◄───────────────────────────────────┤
│ (repeated) │
│ event: complete │
│◄───────────────────────────────────┤
│ │
│ GET /runs/{runId}/report │
├───────────────────────────────────►│
│ │
│ 200 OK {summary, latency, ...} │
│◄───────────────────────────────────┤
For the length of that stream - a load run or a collection run - the Manager can
hold a system wake lock (electron/power-save.ts, prevent-app-suspension), so
an OS sleep timer cannot suspend the machine under a test the user walked away
from and leave the report with a gap it cannot explain. The lock is ref-counted
and token-based: the renderer's run services take one each over power:hold and
hand it back on every terminal path, the main process drops a renderer's holds
when it goes away or reloads, and the blocker stops with the last holder. A run
that stops being watched without ending hands its lock back too: the two
services share one SSE client, so starting a collection run takes the socket
from a streaming load run, and the client tells the displaced service rather
than closing on it in silence, which used to leave that key held for the rest of
the session (issue #1417). A run replaced by another of its own kind hands the
key back on the same path: each service ends the run it is replacing before it
registers the new one, so the key is released and taken again in that order,
rather than the arriving run being handed its own hand-off and freeing the lock
it had just taken. A run an MCP agent started holds the lock on the same terms:
main does not watch runs, it names the run its mcp:data-changed event just
started and the renderer enters the same watch path a dashboard would (issue
1419). The screen may still dim and lock; only suspension is refused.¶
It is off by default, because the machine's power settings are the user's.
Two things turn it on. The standing preference (Settings > Load testing > Keep
the machine awake during runs, keepAwakeDuringRuns in client-settings-store)
is read when a run starts, and with it on every run holds. With it off, a load
run that declares ten minutes or more asks once when it starts
(KeepAwakePrompt), and an answer of "keep awake" takes the lock for that run
only. A collection run is never asked about: it declares no duration, so nothing
in the app can tell a two-second sequence from a two-hour one.
The lock is a request to the OS, not a guarantee. When the host suspends anyway
(a closed lid, a critical battery), main reports the interval to the renderer as
power:suspended / power:resumed, and the app records it against the run and
marks it on the charts and in the run's Events tab. The engine cannot carry that
record: it was suspended too.
System notifications for a run's end are opt-in and off by default. The
renderer decides what is worth saying - it is the only side that knows a run
reached a terminal state, and the only side that can read the opt-in, which
lives in a localStorage-backed store main cannot see - over notify:show
(services/notify.ts); electron/notify.ts decides whether and how, from the
window's focus and the platform's support, and answers notify:availability
for the settings row. Nothing is posted while the window is focused - the toast
already said it. Main treats the request as untrusted: it accepts only the ten
kinds it lists itself, caps the title at 80 and the body at 240 characters, and
drops control characters (issue #2378). A run an agent started over MCP notifies like any other: the
renderer is told the run began and watches it from that moment, so its end
reaches the user who handed it over and walked away - which is the case the
setting exists for (issue #1419). Windows shows nothing at all unless
app.setAppUserModelId matches the shortcut's id; macOS authorizes per bundle
and refuses one whose code signature does not bind its own Info.plist. Ad-hoc
signing satisfies it, and install.sh re-signs what it installs, so an
installed build notifies - but
the dev Electron.app and a bundle dragged straight out of the DMG do not, so
system notifications cannot be exercised by pnpm electron:dev on macOS. That
refusal is caught, latched, and reported in Settings, with the toast standing in
as the fallback.
One event carries a second opt-in of its own: an inbox capturing a request (issue #1388). Every other kind is terminal and rare - a run ends once, an update lands once - and a webhook source can deliver hundreds a minute, so a capture notifies only when the global opt-in is on and that inbox's own toggle is, which sits in the inbox's header rather than in Settings and is off by default. The captures of one window are coalesced into a single notification naming how many arrived, rather than posted one by one, and the window is a property of what a notification is for rather than a setting the user tunes. The stream that hears those captures is held app-wide, for every running inbox whose toggle is on, rather than by the inbox tab: one tab's surface is mounted at a time, so a view-owned stream was silenced by the click onto another tab that ordinarily precedes leaving the window (issue #1400).
Because that answer only exists once something has been posted, Settings can ask
for one: the Preview beside the toggle posts a real notification over
notify:test, which ignores the focus check - the user is looking at the panel
when they press it - but respects the opt-in like everything else: Preview is
disabled while the setting is off, so seeing what the OS does costs turning the
setting on, pressing Preview, and turning it off again if it does not fit,
rather than a button that contradicts the switch beside it. It waits for the OS
rather than reporting what was attempted, so a refusal turns the row unavailable
there and then instead of on the first run that ends.
A run's progress is also mirrored onto the OS chrome, over runs:progress
(services/run-progress.ts to electron/run-progress.ts), so a user in another
application can see how far along a test is without switching back. The renderer
says what the fraction is - it is the only side that holds a run's denominator -
and main says what each platform makes of it: a fill on the Windows taskbar
button, a bar on the macOS Dock icon, and nothing on Linux, where Electron 44
removed Unity launcher support. A run with no denominator (an open-ended load
test, or a collection run whose plan frame - the size the engine publishes on
its stream as the run opens, issue #1398 - never reached the client) shows
indeterminate on Windows and nothing on macOS; a failed run flashes the Windows
error state, and keeps it - the terminal clear that follows skips the run that
just reported a failure, or the flash would be wiped in the tick that painted
it. A failure gets there two ways, and the second is the ordinary one: the SSE
client failing to open the stream at all, and the engine's own complete frame
arriving with status: "failed", which is what a run that fails while being
watched sends (issue #1415). Every other terminal path clears the bar, and main
clears it itself when the renderer that asked for it is destroyed or reloads.
The bar is not the app's own runs only: a run started by an MCP agent is watched
from the moment the main process reports it (startedRun on
mcp:data-changed, issue #1419), so it paints the same fill, and opening its
dashboard tab later attaches nothing new - startMonitoring is idempotent for a
run already being watched. One indicator is all the OS gives an application, and
one run is all the renderer watches: the SSE client is a singleton. A load run
is refused before it starts while another run holds the stream, and so is a
collection run; the refusal names the live run and offers to stop it. An agent's
run, of either kind, is not adopted while another run is live (the single-run
gate, canStartLoadRun in app/src/stores/run-gate.ts, #3351, #3381). The
renderer's own starts are all gated, so a stream is taken from a live run only
as a backstop: the new run closes the old one's stream - and tells its service
so, which hands the displaced run's wake lock back and gives up its bar rather
than leaving both standing (issue #1417). The lock is the half with a visible
outcome: the incoming run claims the indicator before it connects, so the bar is
transferred rather than cleared, and the displaced run's release - named by the
run it speaks for - finds nothing of its own left to wipe. The
superseded run is not stopped and posts no notification: it is still running in
the engine, so the dashboard keeps it live under its lost-stream callout, and
its row reaches a terminal status on the next list read rather than through a
notification for a run nobody is watching. The indicator
follows the run being watched: a run claims it by id when
the renderer starts watching it, and a run that no longer holds that claim is
ignored whether it reports, fails or stops - including a run of the same kind as
the one that took over, and one whose last batched flush lands after it was
superseded, neither of which a claim by kind could tell apart from the live run.
The icon itself carries what the window is not showing, over icon:signal
(services/os-icon.ts to electron/os-icon.ts), on the same split as the bar
above: the renderer reports that a capture landed, that the Inbox is on screen,
that a run failed, and which collections the user has been in, and main decides
whether any of it is worth painting and what this platform can paint. Whether
turns on the window's focus, which is main's question for the reason notify.ts
gives - a capture the user watched arrive is not unread, and a run that failed
in front of them needs no mark. What each platform can show is the other half:
macOS takes a count on the Dock icon (app.setBadgeCount) and a single critical
bounce for a failure, Windows draws both onto the one taskbar overlay it gives
an application, and Linux gets neither, since Electron 44 removed Unity launcher
support. Windows having one overlay and two things to say through it is settled
in favour of the failure while it stands, with the count coming back underneath
it when focus takes the failure off. That focus does not clear the count: those
captures are still unread, and opening the Inbox is what says otherwise. The
overlay images are drawn rather than shipped (electron/os-icon-overlay.ts),
which is what lets a test read a count back instead of a person looking at a
taskbar.
One of those cues does reach Linux, and it is the one that is conditional.
A run reaching a terminal state the user did not ask for flashes the taskbar
button on Windows and Linux (flashFrame) and bounces the macOS Dock once
(bounce("informational")), and it does so only when the system
notifications are off - it is the quieter substitute for the toast the user
declined, not a second cue beside it. The condition is the renderer's, because
the opt-in lives in a store main cannot see, so nothing is sent at all when the
setting is on. macOS takes a bounce rather than a flash on purpose: there
flashFrame bounces until something turns it off, which is the weight a
failed run already gets from bounce("critical"), while the informational
bounce ends by itself and so is the one cue here that needs no clearing. The
flash is cleared by the window's focus, alongside the failed mark.
The icon offers a way in as well as a state, and everything arriving that
way is one kind of thing: an intent, over intent:open
(electron/open-intent.ts). Three doors lead to it. The macOS Dock menu and the
Windows Jump List both list New Request and the three most recently opened
collections, and a click on either is the same request - the Dock menu calls
into main directly, while a Jump List task is a shortcut to the executable and
arrives as a command line, on a cold start as process.argv and on a warm one
as second-instance. A document dropped on the icon is the third: macOS raises
open-file, the other two put the path on that same command line. Both doors
pass the path through isImportableFile first. The packaged app declares .json,
.yaml and .yml as documents it opens (mac.fileAssociations in
electron-builder.json) with role Viewer and rank
Alternate, so it appears under Open With and never takes over as the default for
JSON. Linux lists application/json, application/yaml, application/x-yaml and
text/yaml as the desktop entry's MimeType (linux.mimeTypes; the x-yaml name is what
older shared-mime-info releases give .yml). The entry's Exec ends in %U, so a file manager
may pass a file:// URL rather than a path, and parseOpenIntents decodes it to the path before
the allowlist; a URL that does not name a local file is dropped. Windows registers nothing: NSIS
rewrites the extension's default handler on install and does not restore it, so there the routes
in are Shift-dragging the file onto the taskbar button or Open with > Choose another app > Vayu
(both launch the executable with the path). Intents are
buffered until the renderer reports did-finish-load, because the earliest of
them arrives before there is a window at all, and a dropped document that
vanished into a cold start would look like the app ignoring the double-click.
They are held again whenever a window is created (the macOS Dock rebuilding a
closed one) or the main frame starts loading a new document (a reload after a crash or an
unresponsive renderer; a subframe or same-document navigation does not count), so an intent offered before the new page mounts waits for its
did-finish-load instead of going to a page with no subscriber (#3339).
Main carries the path and never reads the file, but it does record the path as
one the user opened (electron/file-grants.ts, #2357); the renderer reads it
back through the gated specFile:read channel the import batch already uses,
which reads only a document holding such a grant, so nothing here becomes a
second door onto the file system, and the document lands in the Import dialog's
ledger exactly as a picked file does.
See Engine API Reference for complete endpoint documentation.
Sidecar Pattern¶
The Engine runs as a separate process managed by the Electron main process:
- Engine Startup: Electron spawns the
vayu-enginebinary on app launch, alongside creating the window rather than before it - first paint does not wait on the engine - Health Monitoring: The renderer polls
/healthto verify connectivity, and the sidecar watches the child process it spawned - Graceful Shutdown: Engine is stopped when Electron app quits
Lifecycle and operations¶
The sidecar (electron/sidecar.ts) keeps the engine's life as one value, an
EngineLifecycle (issue #3336), changed in one place and published to
listeners on every change:
| State | Meaning |
|---|---|
idle |
Nothing started yet, or a start failed before it had a child |
choosingPort |
A start is picking its port |
replacing |
Stopping an engine so this session's can take its place: one found running at start, or this session's own during a restart |
spawning |
The child is spawned and the readiness poll is running |
ready |
/health answered |
slow |
The 45-second readiness budget is spent but the child is alive; it is still watched |
crashed |
The current child left without being asked to: its exit code, signal, last stderr lines, or the message of a child error |
stopping, stopped |
An intentional stop; once the app is quitting nothing but stopped follows stopping |
A child leaving while the state is replacing or stopping left because it
was asked to, and a previous child's late exit during a restart is not the
current child's: neither is crashed.
start, stop, restart and shutdown run through one queue, so no two of
them drive the child at once. A restart requested while one is queued or
running joins it and gets the same result, so two clicks never spawn two
engines (each spawn mints a grant secret, and a second spawn would leave the
secret with one child while the other survived). A restart requested during the
first start's health poll waits for that start rather than killing the child
the poll is waiting on.
Ownership model¶
The engine binds one port and owns one SQLite database, so exactly one app instance may drive it. The port is 9876 unless another program holds it, in which case the app picks a fallback (below).
- One instance. The app takes
app.requestSingleInstanceLock()before it starts anything. A second launch focuses the running window and exits - it never gets its own engine, and never attaches to the first instance's. A launch from the OS's login item (Settings > General > Start at login) is an ordinary launch: it takes this lock like any other, so a Vayu already running at sign-in is focused, not duplicated. So is the relaunch Windows makes after a restart (--restarted-after-reboot, registered byrestart-registration.ts): an ordinary launch that takes the lock, with nothing special-cased. - The app talks only to the engine it spawned this launch, and hands it a
secret (issue #2356). Each spawn mints a grant secret (32 random bytes, as
hex) and passes it in the child's environment as
VAYU_GRANT_SECRET, never on the command line, which process listings show; it is not logged. The engine takes it out of its environment at start and requires it, as theX-Vayu-Grant-Secretheader, on every write to file trust (allowed folders and picked files, see the API reference). The main process holds it infile-trust-client.ts, the only module that sends it; the renderer and the MCP server never see it. A restart spawns a new engine and a new secret. - An engine of this app's already running at startup is replaced, never
adopted. If an engine serving the app's data directory answers on one of
its ports at startup - an orphan left by a crashed session, or one started by
hand on that directory - it was given another launch's secret or none, and
nothing can hand it this one, so adopting it would leave every allowed-folder
and picked-file write refused for the session. The app asks it to
POST /shutdown, waits for it by the PID in the lock file (vayu.lockin the data directory), kills it by that PID if it outstays the grace period, and spawns its own on the same port. The same stop covers an engine built for another Vayu version (issue #1492), which no longer needs a check of its own. What identifies an engine is its/healthbody (issue #2153):status: "ok"plus a stringversionand a numericworkers. Another program answering only{"status":"ok"}is a held port - never sent/shutdown. A lock PID that is a live Vayu engine but never answers/healthis waited for on the same budget a spawned engine gets, asked to shut down if it answers, and otherwise killed by PID and replaced (issue #1905); a port the lock does not explain is held by another program, and the app moves on to its next port (next bullet). Seedocs/lock-file-handling.md. - Opening the app never stops an engine it does not own (issue #3328).
What makes an engine the app's is the
dataDirits/healthreports (API reference): the app compares it with its own data directory, both resolved and without a trailing separator, ignoring case on Windows only. A Vayu engine serving another directory - avayu-enginerun from a terminal forvayu-cli, or a second app instance on another profile, which the single-instance lock does not cover - holds its port like any other program: it is never sent/shutdownor killed, and the app takes its next port, so two instances with separate data directories run side by side. An engine too old to reportdataDiris never the app's, with or without a live lock: the lock proves the app's engine exists, not that this answering one is it, and stopping a stranger costs more than a fallback port. After upgrading across this change, an orphan of the old release holds its port until it is quit by hand (the port-in-use error names it). The same applies to a standalone daemon: it is left alone only when its--data-dirdiffers from the app's, and the app's is<repo>/engine/datain a development build, so a daemon run fromengine/with its defaults serves the same directory and is replaced. Give a standalone daemon its own--data-dir. - Another program on 9876 moves the engine, it does not stop the app (issue
#2118). The sidecar walks an ordered list: 9876, then 9880-9889 (a fixed list
rather than an OS-assigned port, because the renderer's CSP names its
connect-srcorigins at build time, and clear of the MCP port 9877). A port where the app's own engine answers/healthhas it replaced there (above), a free one is taken, a held one is skipped. The first start fixes the choice for the life of the app: the main process passes it to the renderer once, aselectronAPI.enginePort, and the renderer'sENGINE_BASE_URL, theOriginbridge and the MCP server's engine URL all follow it. The Dock's engine status shows the address while connected. With every port held the app stays up on the disconnected state, the Dock says what holds 9876 ("Another program" or "Another Vayu engine") and to free it, and offers Retry (the renderer was told one port, so Retry looks at 9876 alone), and nothing quits. Tools outside the app assume 9876:vayu-cli --daemonand the stdio MCP launcher'sVAYU_ENGINE_URLneed the address the Dock shows when the app fell back. - Quit leaves nothing behind. Shutdown is
POST /shutdownfirst, then a wait for the process to go, then a name-verified kill by PID if it outstays the grace period. The name check is what keeps a recycled PID from being killed in the engine's place. - A quit during a restart wins. Once the app is quitting, the sidecar
refuses to start an engine, and a restart already in flight is waited out
rather than raced - otherwise a freshly spawned engine outlives the process
that was supposed to kill it. A first start that fails because of the quit,
or with a restart queued behind it, is overtaken rather than failed: the
launch path logs it and neither shows the "Couldn't start Vayu's engine"
box nor quits, since the quit is already happening and the restart answers
engine:restartitself. - An engine that dies after startup is shown, with a way back (issue
#3336). The main process pushes every lifecycle change to the window on
engine:lifecycle(and answers an invoke on the same channel with the current state, for a window that loaded or reloaded after the last push). The renderer keeps thecrashedfacts inengineCrash; the Dock's connection tooltip says how the engine left (signal, exit code or error, with the last lines it printed) and offers Restart, which a crash never did. The lifecycle is facts only: the/healthpoll is still the one writer of the renderer'sengineStatus, and acrashedpush asks it to look again (it invalidates the health query alone) rather than waiting out its 30 s healthy interval (issue #3493). The Dock, the Services drawer, the inbox and mock-server tabs, the dirty-tab close guards and the change feed readselectKnownEngineStatus, which lets a crash outrank aconnectedverdict the poll gave before the push, so the light reads "Engine disconnected" beside Restart and the drawer shows its services stopped, never "Engine connected" and green dots on listeners the crash took with it. The poll's next verdict ends the override, whatever it says: the crash itself stays recorded untilready, which can trail the poll that sees a restarted engine answer, and that engine is connected. A crash pushed inside a restart's start window refetches like any poll there and reads "Starting…". A crash stays recorded through a restart's transient states (replacing,choosingPort,spawning, and theidlea failed restart ends on) and is cleared only byready,slow,stoppingorstopped, so a restart that fails leaves Restart on the Dock. A start that cannot succeed keeps its own sentence (engine:startFailure, a held port with Retry), which takes precedence over a crash. One restart runs at a time across the Dock button and the Settings banner. The engine that comes back is running none of the services the old one held, so the reconnect names them (local services, below). - A dirty editor flushes itself the moment the engine comes back, on an
automatic reconnect (
useHealthQuery) or a manual restart (useEngineRestart) alike - both invalidate every query and then flush every registered save context. A failed auto-save's own retry can be backed off up to a minute behind either, and nothing else pokes it sooner; seedocs/app/state-management.md'ssave-store.tssection for the retry and the Dock's persistent "Not saved" state a failure short of that leaves on screen. - A quit or window-close asks before discarding a flush that did not land
(issue #1489). Both gestures go through one state machine in the main
process,
quit-flow.ts:idle, then the running-services question below, then the flush, then the loss question, thenproceeding, after which a quit hands over toquit-shutdown.tsto stop the engine and the MCP server. The flush waits out its round trip unconditionally (the renderer's ACK, or a 2 s ceiling if it never comes); what matters is what happens once it settles. The renderer'sflushAllresolves to how many contexts saved, failed or stayed pending (a save the editor declined to send); a ceiling with no ACK at all is read the same as a failure, since nothing is known to have landed. Either case holds the quit or close behind one native dialog - "Couldn't save N edits - the engine isn't responding", "Couldn't save N edits - the disk is full" when every failure was the engine's 507insufficient_storage(the result then carriesreason: "disk-full", issue #2423), or "N edits couldn't be saved as they are" when the engine is fine and every loss is a pending edit, Quit/Close anyway or Keep working - built bybuildFlushFailurePromptinsave-flush.tsand shown through the samedialog.showMessageBoxprimitive the crash and unresponsive-window prompts already use. A clean flush proceeds exactly as before, with no dialog, and so does a quit from a signal whatever the flush reported: it logs the result at warn and goes on (issue #1908). Keep working, like Cancel on the services question, returns the flow toidleand forgets both the flush and the services answer, so the next quit or close flushes again and asks again (issue #3335). Each flush carries an id onbefore-quitthat the renderer echoes on its ACK, and an ACK whose id is not the flush in flight is dropped. A renderer that is replaced (a crash recovered, a hung one reloaded, a new window) also resets the flow. Closing one dirty tab (not the whole window) is the same question asked earlier:useTabsStore.closeTabkeeps the tab and toasts instead of unmounting it when the tab is dirty and the engine is notconnected, rather than lettinguseSaveManager's unmount flush fail into a pane that is already gone. - Local services are window-scoped, and the close says so. Everything the
Services drawer starts - webhook inboxes, mock servers, mock issuers - runs
inside the engine, so quitting stops all of it. On Windows and Linux closing
the last window quits; on macOS it hides the window and the app keeps serving
until Quit. Neither one takes a listening service silently: a close or quit
that would stop something names it - "Close Vayu and stop the 2 services it is
running?", with the inbox's port and the mock server's collection - and Cancel
leaves everything up. macOS's window-close asks nothing, having stopped
nothing. The one quit that never asks is a signal:
install.shreplaces a running AppImage that way, and a dialog would hold the upgrade open waiting for an answer nobody is there to give (issue #1363). The flush-failure dialog above is no exception: a signal quit that cannot save its edits would stall on it untilinstall.shkilled the app and orphaned the engine (issue #1908). An engine restart stops them too, whether a crash ended the old engine or the user pressed Restart, and neither asks first. What it does instead is say so afterwards: the renderer keeps what the cached Services lists said was running when the outage began, and once the health poll or the Restart sees the engine back it compares that by id with the engine's fresh lists and raises one toast naming what is no longer running (three by name, then a count), with a View services action (app/src/lib/services-stopped-by-restart.ts, issue #3493). Both reconnect paths report, and one snapshot is pending per outage, so the user hears it once. - A taken port is a loud failure, not a silent one. The engine binds its
port (
--port, default 9876) before it serves, so anything already holding it makes it printCould not bind 127.0.0.1:<port> - ...to stderr and exit 1 rather than report itself listening. The engine never falls back to another port by itself, because a process that silently moves is a quieter failure than none. The app is what chooses a different port, before it spawns the engine, and then tells every consumer (issue #2118, above); it checks the port is free first, so the engine's exit 1 is the race where something takes the port in between. - A database written by a newer engine refuses to open, the same way.
Database::migrate_before_syncreadsPRAGMA user_versionbefore touching anything else and, on a version newer than this build'sSCHEMA_VERSION, throws naming both versions instead of migrating (issue #1492) - the file is never written to. The constructor throw crashes the daemon the same way a bind failure does, so it takes the same path out: exit 1, and the spawn failure's stderr tail (describeSpawnFailureinsidecar.ts) carries the refusal message into the dialog the app already shows for a startup that cannot succeed. - A startup that cannot succeed fails immediately; one that is merely slow
does not. The readiness poll spends a 45-second budget watching the spawned
child as well as the port: an engine that exits first - a missing shared
library, a lock it could not acquire - fails the launch at once, naming the
exit code or signal and the engine's last stderr lines. An engine still alive
when that budget runs out is not killed for it: the sidecar moves it to
slowand keeps probing, the launch path logsEngineNotReadyError, and the renderer's health poll adopts it the moment it answers. When the sidecar's own probe sees the answer first it moves toreadyand the main process runs the file-grant sync the slow path skipped (not the log floor, which is applied once per launch and already was, atdebug). Quitting there used to end launches that were seconds from succeeding. - The window is created alongside the engine, not after it. First paint must
not wait on a process whose own startup housekeeping is allowed to run for 45
seconds -
db.init()does orphan reconciliation, inbox cleanup and a page-reclaim rewrite before the engine listens at all, and that whole window used to be blank screen. Nothing is lost by overlapping them: the renderer tolerates an absent engine by design, polling/healthitself and rendering the starting state until one answers - in the Dock and in every query mounted at first paint, which retry a refused connection through the start window instead of failing (lib/query-client.ts). MCP still starts after the window, for its own reason - it reads a config file, and a corrupt one must not cost the user a window. - MCP is loaded after the window too, not merely started there. Placing the
start call late does nothing about the import: the main process is unbundled,
so Node's ESM loader walks
main.ts's static import graph and evaluates every module in it beforeapp.whenReadyfires at all. Reaching through themcp/index.jsbarrel for anything therefore evaluated the MCP SDK, zod and a 7,300-line tool registry - ~250-300 ms ahead of the window on every launch, including the ones where MCP is switched off, since the barrel also carried the preference that decides.main.tsnow imports the three self-contained modules it needs at startup (mcp/config,mcp/store,mcp/connect) and pulls the barrel through a cached dynamicimport()inside the MCP lifecycle's service factory, behind the enabled check.startup-import-graph.test.tsholds the graph to that.
Development vs Production:
- Development: Engine binary at engine/build/vayu-engine
- Production: Engine binary packaged in Vayu.app/Contents/Resources/bin/vayu-engine
See App Architecture - Sidecar for implementation details.
Data Flow¶
Single Request Execution¶
- User builds request in RequestBuilder
- Manager sends
POST /compose; the engine interpolates{{variables}}and resolvesinheritauth - Manager sends
POST /executeto Engine with the composed payload - Engine runs pre-request script (if provided)
- Engine executes HTTP request via libcurl
- Engine runs test script (if provided)
- Engine returns response with timing and test results
- Manager displays response in ResponseViewer
Load Test Execution¶
- User configures load test (mode, duration, concurrency)
- Manager sends
POST /runsto Engine - Engine starts load test and returns
runId - Manager connects to SSE stream (
/runs/{runId}/live) - Engine streams real-time metrics (RPS, latency, errors)
- Manager updates dashboard in real-time
- When test completes, Manager fetches final report (
/runs/{runId}/report)
Outbound Transport¶
Every request the engine puts on the wire - a design send, a load run, an SSE
stream, an OAuth token fetch, a spec import by URL, a monitor scrape, a script's
own pm.sendRequest - leaves through one transport policy, resolved from
Settings > Network & connectivity at the point of use and applied by a single
function (detail::apply_transport_policy). There is one hop between the engine and the
target and it is either absent or a proxy:
proxyMode decides which:
environment(default) - libcurl's ownhttp_proxy/https_proxy/no_proxypickup. This is the behaviour a terminal-launched engine already had; a desktop launch usually inherits none of those variables.system- the proxy this computer is configured with. The engine cannot resolve that itself, which is the whole reason this mode has a mechanism rather than a rule: the two networking stacks are disjoint. Chromium resolves the operating system's proxy (and its PAC script) for the Electron shell and reads it on its own; libcurl, which carries every request the user sends, sees none of it. So the main process - the only place both are visible - resolves and writes the answer into theproxySystemUrlsetting, where this mode reads it, at startup, when the machine wakes, and when the renderer sees the network change. Two limitations follow and are stated where the mode is chosen: a PAC script is resolved once, against a probe URL, and the one answer applies engine-wide (per-URL PAC needsmanual); and a headless engine has no app to push it a value, so an emptyproxySystemUrlfalls back toenvironmentrather than tooff.manual- the configuredproxyUrl, written the way curl takes it (scheme://user:password@host:port, which covers SOCKS and basic proxy auth).off- no proxy at all, environment variables included.
proxyBypass (curl's NOPROXY semantics) exempts hosts from the proxy in
any proxying mode. A failure of the hop itself - an unresolvable proxy host,
a proxy that is down, a refused CONNECT, a forwarding proxy's 407 on an
http:// request - is reported as its own PROXY_ERROR, never as the target's
CONNECTION_FAILED or as the server's own answer (a load run still counts that
407 as a status). Cookies are unaffected: libcurl matches them on the origin
host, never on the proxy.
The same policy carries who the engine trusts. customCaCertificates holds
pasted PEM anchors, materialized as a bundle beside the database and added to
the platform's own trust rather than replacing it, so a TLS-inspecting proxy or
an internal authority is verifiable on every one of those paths at once. All
three platforms verify with one TLS backend - OpenSSL, pinned in
engine/vcpkg.json and asserted per CI leg - so additive means one of two
things depending on where the platform keeps its anchors: Linux and macOS read
their bundle from disk and the materialized file is that plus the paste, while
Windows keeps its in the certificate store and the engine loads it with
CURLSSLOPT_NATIVE_CA beside the bundle. macOS sets that flag too, so the
Keychain is asked whenever a certificate does not verify against the file. Per request, the Settings tab's
Verify TLS certificate row turns verification off for one endpoint - stored,
sent on every send and load test, and painted as a warning while it is off. See
TLS trust settings for the
per-platform detail, including what the Windows store does not supply.
The same trust and the same switch apply to the proxy's own handshake when
proxyUrl is an https:// URL: libcurl keeps those options separate from the
target's, so the engine writes the proxy twins (CURLOPT_PROXY_CAINFO,
PROXY_SSL_OPTIONS, PROXY_SSL_VERIFYPEER / _VERIFYHOST) from the same
values, and a refused proxy certificate is reported as the proxy's.
It also carries what the engine proves it is. An mTLS endpoint asks the
client for a certificate, and a certificate belongs to the host being called
rather than to one request - the transfer that needs it is as often a token
fetch, a redirect or a script's pm.sendRequest. So the engine keeps a
registry of host to certificate (Settings > Network & connectivity), matches an
entry per transfer by host and optional port - an exact name, or *.example.com
for every subdomain of it but never the domain itself - and presents it on every
one of the paths above without any request naming it. A design send and a
stream follow a redirect one transfer per hop, so each hop is matched against
its own host; a load run follows one transfer per hop the same way, so the
certificate reaches the origin each hop names. Only the file paths are
stored, so the private key stays where the user's own tooling put it; a
cert-authenticated exchange reports which entry it used, live and from History
alike. See Client
certificates.
Because all three of those - the hop, the trust and the certificate - fail at
the first real request and libcurl names the endpoint when they do, the same
Settings screen carries a connection test: one policy-honouring send
(POST /diagnostics/connection) whose answer says which hop refused, so a
wrong proxy URL or a missing corporate CA is caught where it was configured.
It returns an outcome and never the response body. The other half of the same
honesty rule is on the way in: pasting a curl command imports what it can and
names what it could not - -x, --cert, --cacert and the rest - with a
pointer to the setting that owns each intent, rather than silently dropping
them.
Variable Resolution¶
The engine owns execution-time resolution (POST /compose); the renderer
keeps a preview-only copy. Later sources win:
Globals < Collection chain (root to leaf) < Active environment < Bound data row.
See Variable resolution for the rules.
Security¶
- Script Sandboxing: QuickJS contexts are isolated with no filesystem
access. Scripts can make HTTP requests through
pm.sendRequest, subject to the same scheme allowlist as the request itself: onlyhttpandhttpsURLs are sent, checked after variables resolve, and every transfer handle is restricted to those two protocols for redirects too (URL schemes). - Local-Only Communication: Control API only binds to
127.0.0.1(port 9876 by default; the app may choose a fallback, see Ownership model) - The engine serves no browser: it sends no CORS header, and before any
route runs it refuses a
Hostthat is not127.0.0.1:<port>,localhost:<port>or[::1]:<port>(DNS rebinding) and any request carrying anOriginheader; anOPTIONSpassing the Host check is answered204with nothing else. A web page in the user's browser can neither read the engine nor change it: a scriptlessGET(an<img>, a navigation) still reaches aGETroute, gets an opaque answer, and noGETroute has a side effect, bar one resource it could hold: a change-feed stream takes a pool thread, soGET /changesopens only on a single-use id fromPOST /changes/subscriptions, which a page cannot send, and a page cannot fill the stream slots to lock the app out. Local tools (the MCP server,curl, a script) send noOriginand are unaffected (Who may call the API). - The shell carries the renderer past that gate: the renderer is a browser
context too. The Electron shell (
app/electron/engine-origin.ts), on the main window's session, strips the renderer'sOriginandRefererfrom requests to the engine's own address,http://127.0.0.1:<port>/*for the one port the app chose (the filter registers every candidate port, since it is fixed at startup, but only the chosen one is bridged), and supplies the CORS response headers the renderer needs, so the renderer reaches the engine like any local tool. That URL filter is the whole boundary, which is why nothing but the app's own document may load in that session. - HTML Preview runs nothing and fetches nothing: the response pane renders
the server's markup in an iframe with
sandbox=""(noallow-scripts, noallow-same-origin), so it runs no script and never shares the renderer's origin or reacheswindow.electronAPI. A Content-Security-Policy injected ahead of the markup blocks every network subresource (onlydata:images, fonts and media and inline styles load), and<base target="_top">keeps ordinary links inert because the sandbox refuses top navigation (app/src/components/shared/response-viewer/preview-document.ts). - No response caching: every engine response carries
Cache-Control: no-storeand the renderer's fetch client asks forcache: "no-store"as well (#1507). Nothing the engine answers is valid to replay from a browser's disk cache - it is a live read of state (a run, a request, a collection) that changes under the client, and TanStack Query, not the HTTP cache, already holds whatever the renderer keeps between polls. - Context Isolation: Electron renderer runs in isolated context (no Node.js access)
- Second layer behind it (#1780): the built
index.htmlcarries a Content-Security-Policy<meta>(stamped byvite-plugins/csp-meta.tsfromelectron/renderer-csp.ts, hashing the one inline pre-paint script, nounsafe-eval,connect-srclimited to the app and the engine origin,form-action 'none'), a<meta>so it ships inside the document whose script it hashes; the dev server is exempt because its React-refresh preamble is inline. The packaged document is served from the privilegedvayu-app://app/scheme (electron/app-protocol.ts, #2380), notfile:, so'self'names that one origin rather than every local file. What thefile:builds kept in localStorage is carried over once, on the first packaged launch, from a script-less stub page on thefile://origin in a hidden, preload-less view (electron/legacy-storage-migration.ts); it is the onefile:load left, and it is retired with that module. Device permissions (camera, microphone, geolocation, notifications) are denied on the default session and on every OAuth partition (electron/permissions.ts).update:openReleasePagetakes no argument and opens only the release page the updater offered. Electron fuses turn offELECTRON_RUN_AS_NODE,NODE_OPTIONS,--inspect, non-ASAR loads and the extra privileges Electron grants afile:page in a packaged build, andisDevelopmentBuild()(electron/dev-mode.ts) requires!app.isPackaged. - The updater installs only a verified installer (#2372): on the silent
platforms (Windows, Linux AppImage)
electron/updater.tsholds the downloaded file back untilelectron/update-attestation.tshas looked up its SHA-256 in GitHub's attestations API, verified each Sigstore bundle against the public-good trusted root (refreshed over TUF byelectron/sigstore-trusted-root.ts), and found the signer to berelease.ymlinathrvk/vayuat the tagv<version>with a SLSA v1 subject naming that digest. Theverifieddownload state, restart-to-install and the quit-time install all wait for it; a failure moves the state torefusedand the file is never installed. Any failure, including a network one, refuses: there is no path that accepts after an error. Both requests, the attestation lookup and the TUF refresh, go through the one injectedfetch(Electron'snet.fetch), so both follow the system proxy (#2738). The check proves the file came out of that workflow run, not that the run was honest; that limit is stated in SECURITY.md. - No Cloud Sync: All data stored locally in SQLite database
- No spellchecker: every window the app opens - the shell and the OAuth
sign-in window - is created with
spellcheck: false, so Chromium checks nothing the user types. That option alone does not stop the Hunspell dictionary download (Google's CDN, on Windows and Linux), which belongs to each session rather than each window;electron/spellcheck.tstherefore empties the spellchecker language list of every session as it is created (app.on("session-created"), registered beforeapp.whenReadyso the default session and the OAuth partition are both covered), and nothing is fetched. Monaco's editors are unaffected either way; they own their own text area. - Proxy credentials: stored in the
proxyUrlsetting as plaintext in SQLite, the same way every other stored credential is. Settings draws that one field as aSecretInput(masked until revealed, #1806), keyed on the setting's name; the stored value and the engine's API are unchanged. libcurl derives theProxy-Authorizationheader from the URL, and that header is on the redaction list, so credentials do not reach a stored trace. The engine's startup log redacts them too, with or without a scheme (#1781). - Client-certificate keys: never stored. The
client_certificatestable holds the paths of the certificate and key files - one path where the certificate is a PKCS#12 bundle carrying both - and the engine opens them at send time. The key's passphrase is the one part that is stored, plaintext, on the same precedent as every other credential above - and the API never echoes it back, answeringhasPassphraseinstead.
Performance Characteristics¶
- Engine: Tens of thousands of requests per second (target/hardware dependent; ~45k req/s tuned on loopback in internal testing)
- Lock-Free Design: High-performance metrics collection with minimal contention
- Async I/O: Uses
curl_multifor concurrent request handling - Load models:
constant_rpsis open-loop (dispatch at a fixed rate);constant_concurrency,ramp_up,iterationsandcapacityare closed-loop (hold a target in-flight count).capacityis the one whose target adapts to what the run measured, stepping up until latency or the error share breaks its budget. See Engine Architecture. - Efficient Caching: TanStack Query caches server responses in Manager
File Locations¶
Development¶
- Engine Binary:
engine/build/vayu-engine - Engine Data:
engine/data/(database, logs) - App Source:
app/src/ - App Build:
app/dist/
Production¶
- macOS:
Vayu.app/Contents/Resources/bin/vayu-engine - Windows:
resources/bin/vayu-engine.exe - Linux:
resources/bin/vayu-engine - Beside the engine, loose in
resources/(extraResources, outside the asar so the OS can open them):icon.pngandTHIRD_PARTY_NOTICES.txt(#2693; reached from Help › Third-party notices and Settings › General) - Data Directory (
app.getPath("userData"), named bymain.tsfromUSER_DATA_DIR_NAMEinapp/electron/constants.ts): - macOS:
~/Library/Application Support/Vayu/ - Windows:
%APPDATA%/Vayu/ - Linux:
~/.config/Vayu/
See: Engine Architecture | App Architecture | Engine API Reference