Tauri desktop application lifecycle
World Monitor's desktop application is a Tauri shell around the web client. It joins a Rust host, a local Node API sidecar, native permissions, and platform packages into one desktop product. The lifecycle keeps local services and OS access controlled while the same installed client serves the product's in-app variants. See Desktop and external clients for the wider client model.
Application model
Application identity
The desktop product has one identity: World Monitor. Its package name, binary name, application identifier, and version describe one product. The installed client switches between the Tech, Finance, Commodity, Energy, and Happy variants instead of creating separate installers.
This model keeps updates and downloads on one release line. An in-app variant is therefore a client feature rather than a new desktop package family.
References: src-tauri/tauri.conf.json• L3-7 src-tauri/tauri.conf.json• L45-47
Desktop boundaries
The Rust host is the trusted desktop boundary. It gives the web client selected OS actions such as secret storage, local cache access, child-process control, safe URL opening, and local API access through Tauri commands.
The web client can still run as a normal web client when the native bridge is absent. Desktop-only permissions are not assumed by the browser surface.
References: src-tauri/…/main.rs• L480-611 src-tauri/…/main.rs• L930-1075 src-tauri/…/main.rs• L1267-1279
Runtime lifecycle
Host startup
The Rust host starts before the main client is ready. It loads the desktop cache and stored secrets, prepares logs, and launches the local API sidecar with the resources and settings for that session.
The host stores the sidecar child, its per-launch token, and the port confirmed by the sidecar. It refuses to use the preferred port when the sidecar has not proved which port it owns. On exit, it flushes the cache and stops the child.
References: src-tauri/…/main.rs• L2354-2533 src-tauri/…/main.rs• L2765-2783 src-tauri/…/main.rs• L2823-2831
Local API sidecar
The local API sidecar is a Node service that gives the desktop client one local request path. It runs local handlers where the desktop has the needed resources and sends selected requests to the cloud where state or services exist only there.
The Rust host gives the sidecar a unique transport token and a preferred port. The sidecar writes the port that it actually binds to a file. A protected request must carry the transport credential. A signed-in user's bearer remains a separate caller credential and is forwarded only when the cloud path needs it.
The sidecar starts in a default-deny state when its transport token is absent. It keeps health and the YouTube embed bridge available without that token because those paths do not expose desktop secrets. It also limits request size, concurrent upstream work, queue growth, and idle time so a bad local or remote peer cannot hold the service open indefinitely. Outbound calls honor both the caller's cancellation and the sidecar's own deadline while a response body is still arriving. Self-host relay responses can stream after headers arrive instead of waiting for the full model answer.
The desktop request path follows this sequence:
flowchart LR
W[Web client] --> H[Rust host]
H -->|confirmed port and session token| S[Local API sidecar]
S --> L[Local handlers]
S --> C[Cloud routes]
S --> P[Approved providers]
References: src-tauri/…/main.rs• L2426-2463 src-tauri/…/main.rs• L2502-2530 src-tauri/…/local-api-server.mjs• L2187-2213 src-tauri/…/local-api-server.mjs• L2578-2592 src-tauri/…/local-api-server.mjs• L2655-2832 src-tauri/…/local-api-server.test.mjs• L1438-1475 src-tauri/…/local-api-server.test.mjs• L5411-5463
Request routing
The sidecar chooses the cloud for routes whose useful data lives in cloud state or seed snapshots. It can use a local handler first for other routes and fall back to the cloud when the local result fails and desktop fallback is enabled. It keeps the desktop Ollama translation path local when the user selects Ollama.
Docker uses a different trust model. It disables ordinary cloud fallback and native administration. When enabled, it can relay selected requests with the browser user's own desktop key. The key is checked by the cloud and is removed from the request before local handlers or other cloud paths see it. It can reach only explicitly configured private service origins.
The Rust host now limits which sidecar paths the renderer can proxy. It normalizes the path and allows API routes plus two settings diagnostics routes. Secret update and validation routes remain host-only, and unknown local-* routes are rejected.
References: src-tauri/…/local-api-server.mjs• L1267-1479 src-tauri/…/local-api-server.mjs• L1551-1615 src-tauri/…/local-api-server.mjs• L2115-2241 src-tauri/…/main.rs• L514-611 src-tauri/…/main.rs• L1988-2008 src-tauri/…/local-api-server.test.mjs• L329-516 src-tauri/…/local-api-server.test.mjs• L2491-2528
Window lifecycle
The desktop application uses separate windows for the main client, settings, live channel management, and YouTube sign-in. The Rust host creates and focuses these windows when the web client requests them.
The live channel window accepts only a World Monitor origin or a local development origin because it receives trusted desktop actions. The YouTube sign-in window has a smaller permission set because it displays an external-origin flow. On macOS, closing the main window hides it and a dock action shows it again.
References: src-tauri/…/main.rs• L41-42 src-tauri/…/main.rs• L1310-1369 src-tauri/…/main.rs• L2787-2821
Authentication and secret storage
Desktop authentication
The Rust host keeps desktop authentication state outside renderer code. The embedded webview uses a narrow Clerk Frontend API relay. Browser-only sign-in uses the system browser and returns through a short-lived loopback callback.
The renderer receives sign-in status and safe result fields. It does not receive the Clerk client token, browser ticket, or verification values. A failed browser flow leaves the current session unchanged.
References: src-tauri/…/main.rs• L614-750 src-tauri/…/main.rs• L778-921 src-tauri/…/main.rs• L924-928
Provider secrets
User provider keys live in the platform secret store and are loaded into the host for the current run. The host passes approved values to the sidecar without exposing the full vault to the renderer. Settings can add, validate, or delete supported keys through host commands.
Linux can use the kernel session keyring when Secret Service is unavailable. That fallback does not survive reboot. When the normal store returns, the host reconciles the fallback so newer changes and deletions do not restore stale keys.
References: src-tauri/…/main.rs• L134-377 src-tauri/…/main.rs• L960-1075 src-tauri/…/main.rs• L2468-2487
Browser sign-in
The browser sign-in flow binds a loopback callback to one active request. Rust opens the World Monitor sign-in page, checks the returned flow state, exchanges the code for a short-lived ticket, and redeems that ticket through the Clerk relay.
The ticket is single-use and remains in Rust until redemption. Only a successful redemption replaces the stored client, so cancellation, expiry, or an incomplete response does not sign the user out.
References: src-tauri/…/main.rs• L778-921 src-tauri/…/main.rs• L924-928
Capabilities and network safety
Window capabilities
Tauri capability files define which native permissions each window can use. The main and settings windows receive the normal core capability. The live channel and YouTube sign-in windows receive only basic window operations.
The capability assignment and the Rust window-label checks form one security contract. A new window or native command must satisfy both before it can reach trusted desktop actions.
| Window | Role | Capability level |
|---|---|---|
main | Primary World Monitor client | Core default |
settings | First-party settings surface | Core default |
live-channels | Channel management | Window operations only |
youtube-login | External sign-in surface | Window operations only |
References: src-tauri/…/default.json• L1-7 src-tauri/…/settings.json• L1-7 src-tauri/…/live-channels.json• L1-7 src-tauri/…/youtube-login.json• L1-7 src-tauri/…/main.rs• L480-504 src-tauri/…/main.rs• L1310-1369
Network boundaries
The webview content security policy names the allowed API, map, media, login, and embedded-content origins. The host opens only HTTPS URLs, with HTTP allowed for localhost development. The sidecar accepts only Tauri, localhost, loopback, and approved World Monitor origins.
Sidecar outbound requests resolve and check public addresses before connection. The request then uses the checked address so DNS changes cannot redirect it into a private network. Desktop mode permits only the configured Ollama origin for local model work. Docker has separate allowances for its configured private relay, Redis, and LLM origins. These private exceptions come from exact configured origins rather than from request-supplied addresses.
References: src-tauri/tauri.conf.json• L31-33 src-tauri/…/main.rs• L1267-1279 src-tauri/…/local-api-server.mjs• L227-264 src-tauri/…/local-api-server.mjs• L392-563 src-tauri/…/local-api-server.test.mjs• L1825-1939 src-tauri/…/local-api-server.test.mjs• L2011-2130
Local request protection
The Rust proxy normalizes paths before it sends them to the sidecar. It allows API routes and settings diagnostics but keeps secret-management routes host-only. It bounds request and response bodies and strips renderer-supplied authorization from the host-to-sidecar hop.
The sidecar removes its transport token before local handlers or cloud requests run. It keeps caller identity separate from transport authentication. This prevents a renderer credential from becoming a local service credential and prevents the local token from crossing into an upstream service.
References: src-tauri/…/main.rs• L514-611 src-tauri/…/main.rs• L1988-2008 src-tauri/…/local-api-server.mjs• L830-901 src-tauri/…/local-api-server.mjs• L2185-2229 src-tauri/…/local-api-server.test.mjs• L300-327 src-tauri/…/local-api-server.test.mjs• L1438-1475
Build and packaging
Build inputs
The desktop build creates the web client and then assembles the native host with the sidecar, route bundles, shared data, configuration, notices, and Node runtime. The Tauri configuration points the host at the built client and lists the resources that must travel with the application.
The Rust manifest and lockfile define the host's native support and locked dependency set. Release compilation favors a small self-contained binary with link-time optimization, one code unit, symbol stripping, and abort-on-panic behavior. The lockfile records the resolved native stack that supports Tauri, WebView, secret storage, and HTTP access.
References: src-tauri/tauri.conf.json• L7-11 src-tauri/tauri.conf.json• L55-65 src-tauri/Cargo.toml• L1-31 src-tauri/Cargo.lock• L5260-5274
Platform packages
One binary serves every in-app variant. The configured release packages cover macOS app and disk image formats, Windows installers, and Linux AppImages. Platform settings add Windows digest and installer metadata, macOS hardened runtime support, and bundled Linux media libraries.
The bundled Node runtime and sidecar resources are part of the installed application. A package that contains the web shell but not those runtime resources is incomplete even if compilation succeeds.
References: src-tauri/tauri.conf.json• L35-81 .github/…/build-desktop.yml• L88-237
Release artifacts
Desktop release work produces platform artifacts from the same versioned product. The release process must keep the package version, native metadata, and published download set aligned before users receive an update.
The workflow builds macOS ARM64 and x64, Windows x64, and Linux x64 and ARM64. Each leg uploads to a draft release. The release becomes visible only after all expected World Monitor assets pass the complete-set check. A published release is not a place to repair a missing platform asset.
Client environment checks also protect the shipped feature set. A non-draft release stops when required sign-in, entitlement, map, relay, or cloud settings are empty. Draft builds may continue for inspection, but they warn that those capabilities will be disabled.
References: .github/…/build-desktop.yml• L1-29 .github/…/build-desktop.yml• L48-86 .github/…/build-desktop.yml• L88-219 .github/…/build-desktop.yml• L318-392 .github/…/build-desktop.yml• L506-617
Desktop checks
Developer preflight
Desktop development checks validate the Node and Rust toolchains before Tauri starts. Linux checks also cover the webview, GTK, HTTP, rendering, and packaging libraries needed by the native build.
The release workflow uses pinned Node and Rust toolchains. It installs the Linux libraries, checks version consistency, audits the locked Rust dependency floors, and verifies the bundled Node payload before packaging.
References: .github/…/build-desktop.yml• L136-219 .github/…/build-desktop.yml• L221-237 src-tauri/Cargo.toml• L8-31
Runtime compatibility
The Linux host adjusts its display and media environment for known desktop conditions such as virtual machines, NVIDIA sessions, Wayland, and AppImages. These safeguards aim to prevent blank webviews, broken video, graphics failures, and conflicts between bundled and host libraries.
The AppImage must keep its media and graphics runtime self-contained. The workflow removes GPU libraries that should not ship in the image, prefetches AppImage tools, and launches the result under a virtual display to catch startup failure after packaging.
References: src-tauri/…/main.rs• L2553-2729 .github/…/build-desktop.yml• L297-316 .github/…/build-desktop.yml• L410-483 src-tauri/tauri.conf.json• L77-80
Sidecar validation
The host tests the desktop contract rather than only individual commands. It checks path normalization, allowed proxy routes, supported secret handling, late sidecar readiness, and the rule that a missing port never falls back to an unverified default listener.
The sidecar test suite covers authentication separation, cloud sessions, cloud-preferred data, local Ollama behavior, Docker restrictions, resource layout, registration input, upstream cancellation, request-body handling, RSS and relay containment, SSRF protection, response streaming, and deadline cancellation. It also checks that malformed or stalled requests return controlled errors without stopping later requests or permanently consuming shared upstream capacity.
These checks protect the gap between a sidecar that starts and one that safely serves the desktop. They also verify that a streamed relay can pass data without buffering it and that a disconnected client releases its work.
References: src-tauri/…/main.rs• L1948-2024 src-tauri/…/local-api-server.test.mjs• L20-62 src-tauri/…/local-api-server.test.mjs• L223-327 src-tauri/…/local-api-server.test.mjs• L329-682 src-tauri/…/local-api-server.test.mjs• L1478-1707 src-tauri/…/local-api-server.test.mjs• L1825-2130 src-tauri/…/local-api-server.test.mjs• L5411-5463
Change checklist
When these files or sections are changed, remember to consider these:
- A new Tauri command, window, or external origin must stay aligned across Rust label checks, capability files, the content security policy, and the web client bridge.
- A sidecar startup change must preserve the per-launch token, confirmed port file, child identity check, and refusal to guess the default port.
- A sidecar route change must preserve the distinction between local work, cloud-preferred state, Docker relay paths, and the desktop-only Ollama exception.
- A transport or caller-auth change must keep the sidecar token separate from user bearer credentials and remove both from the correct upstream boundary.
- A renderer proxy change must preserve path normalization, the API-only allowlist, the host-only secret routes, and request and response size limits.
- An outbound timeout change must combine caller cancellation with the sidecar deadline and keep the limit active through a stalled response body.
- A shared upstream limiter or streamed-response change must release its slot on every terminal request or response event, including client disconnects and body stalls.
- A resource or runtime layout change must update the Tauri resource list, bundled Node payload, and packaged-resource checks together.
- A secret-store change must preserve Linux fallback reconciliation so newer updates and deletions cannot be replaced by stale session data.
- A sign-in change must preserve loopback callbacks, flow-state checks, ticket expiry, single-use redemption, and the current-session-on-failure rule.
- A package or version change must keep the Tauri metadata, Rust package metadata, release tag, and artifact naming contract aligned.
- A release workflow change must keep every supported platform in the draft-first completeness gate before
/api/versionor/api/downloadcan advertise it. - A network exception must remain tied to an exact configured origin. Do not replace it with a broad private-network allowlist.
- A Linux packaging or runtime change must be checked against both native prerequisites and an installed AppImage launch path.
Important failure modes
| Trigger | Consequence | Guard |
|---|---|---|
| The sidecar does not report its bound port | The client cannot use local API work instead of sending its token to an unrelated listener | Port-file confirmation, child identity checks, late recovery, and no default-port fallback |
| The renderer proxies a secret-control or unknown local route | A renderer path can reach host-only administration or an unintended sidecar handler | Normalized API allowlist and explicit route denylist |
| The sidecar token is missing or invalid | Protected local API requests fail closed | Default-deny auth gate and per-launch token |
| A caller bearer is treated as the transport token | User identity can be lost or an internal credential can cross an upstream boundary | Separate headers and transport-token removal |
| A caller cancellation is replaced by an upstream deadline | A disconnected desktop request can keep consuming sidecar and upstream capacity | Combined caller/deadline signals and body-stall checks |
| A shared upstream slot is not released after a stream error or disconnect | Later local requests wait forever even though the upstream is no longer active | Idempotent terminal-event handling and release in the request cleanup path |
| A cloud-preferred route is served by an empty local handler | A desktop panel can appear empty without a clear error | Cloud-preferred route rules and sidecar routing tests |
| An upstream response stalls or the desktop client disconnects | Shared sidecar capacity can leak or a request can hang | Idle bounds, stream terminal handling, and abort propagation |
| A self-host relay response is buffered or cloud headers pass through unchanged | Model output can appear frozen or the local origin can receive cloud-only policy or cookie headers | Header filtering and unbuffered response streaming |
| A handler fetches a private or rebinding host | The sidecar can become a local-network pivot | DNS and IP checks with pinned outbound addresses |
| A Docker RSS proxy client exceeds its share or queue capacity | One viewer can delay feeds for other viewers or memory can grow without bound | Per-client limits, bounded queue, body cap, and timeout |
| A browser callback has the wrong state or arrives after expiry | The desktop keeps its current session and rejects the new sign-in | Loopback restriction, flow state, deadline, and single-use ticket |
| A renderer invokes a command from an untrusted window | Native actions or secrets can cross a window boundary | Window-label checks and per-window capabilities |
| A packaged sidecar script, route bundle, shared module, or Node runtime is absent | The web shell can open without working desktop API features | Tauri resource list, runtime verification, and resource-layout tests |
| Linux bundled media or graphics libraries conflict with host libraries | The installed app can show a blank webview or broken media | Runtime environment safeguards and bundled media framework |
| Required release environment values are empty | Shipped sign-in, entitlement, map, relay, or cloud features are silently disabled | Non-draft client-env preflight |
| A release has a version mismatch or missing platform package | Updates can point users to an incomplete or incompatible artifact | Version checks, draft-first publishing, and complete-set asset validation |
Key files
| File | Why to read it |
|---|---|
| src-tauri/tauri.conf.json | Defines product identity, web client entry, content security policy, resources, and package targets. |
| src-tauri/…/main.rs | Describes the Rust host boundary, sidecar lifecycle, windows, secrets, cache, sign-in commands, URL rules, proxy allowlist, and Linux runtime safeguards. |
| src-tauri/…/local-api-server.mjs | Defines local and cloud request routing, transport authentication, provider access, self-host relay behavior, outbound limits, streamed responses, and upstream safety rules. |
| src-tauri/…/local-api-server.test.mjs | Shows the sidecar contract for cloud preference, auth separation, Docker behavior, local Ollama work, resource layout, request containment, RSS and relay safety, and deadline cancellation. |
src-tauri/capabilities/ | Defines the native permission boundary for each desktop window. |
| src-tauri/Cargo.toml and src-tauri/Cargo.lock | Define the native host package, release profile, features, and locked dependency set. |
| .github/…/build-desktop.yml | Defines cross-platform build inputs, client environment checks, signing paths, artifact validation, smoke checks, and atomic release publication. |
| src-tauri/…/clerk_relay.rs | Defines the narrow Clerk Frontend API boundary used by the host. |
| src-tauri/…/desktop_sign_in.rs | Defines the browser sign-in callback, ticket, and flow-state rules. |