Warp/apps/desktop/README.md

Warp desktop client

The web client in a native window, built with Wails v3. Every screen is the web client's: warp-desktop embeds the same build warp-web does and serves it through the same Go package (apps/web/host), so web and desktop don't drift apart. It runs on Windows (WebView2), macOS (WKWebView) and Linux (WebKitGTK).

window ──► wails.localhost ──► shell (this app)  ── the web client, /config.json
   │                                                 first-run page, links
   └──────────────────────────────────────────────► homeserver /_matrix/*

Unlike warp-web, the desktop app isn't installed next to one homeserver, so it proxies nothing. The client calls the homeserver directly, the way any Matrix client does; homeservers answer CORS for every origin. The Content-Security-Policy allows the homeserver plus any https: and wss: origin, because the call backend (the LiveKit JWT service and SFU) is learned from the homeserver at run time and can't be listed in advance.

What it adds to the web client

• First run asks for the homeserver. A server name (example.org) or an address. Discovery follows /.well-known/matrix/client and checks /_matrix/client/versions. If the well-known document names an address that doesn't answer, the typed address is used when that one works. File → Change homeserver… asks again. A session already signed in keeps the server it signed in to until you sign out, so changing the homeserver never sends one server's access token to another.
• Links to other sites open in the system browser. That covers a URL in a message, target="_blank" and window.open. Without this they would replace the app in its window or open a bare webview window. /_desktop/links.js does it; the shell adds a <script> tag for it to index.html. Only http, https and mailto URLs are opened.
• One instance at a time. Sessions and encryption keys live in the webview's storage, and two instances on one store would both sync and use the same one-time keys. Starting the app again brings the open window forward.
• System notifications. New messages and incoming calls show as the system's own notifications (Windows toasts, Notification Center, the freedesktop daemon), one per room; clicking one opens the room. The client decides what notifies, by the account's push rules (apps/web/src/stores/notifications.ts), and hands it to the shell through window.warpDesktop, which /_desktop/bridge.js adds; the shell shows it with Wails' notifications service. On macOS they need the bundle (make desktop-macos), not the bare binary.
• The tray and the unread count. A tray icon (menu-bar icon on macOS) with Open and Quit. Closing the window hides it and the app keeps running there, so notifications still arrive; the first time, a notification says so. File → Quit (Ctrl+Q) ends it. The window title and the tray's tooltip follow the page title, and the number of unread rooms goes on the taskbar button (Windows) or the Dock icon. On a Linux desktop with no tray (GNOME without an AppIndicator extension), starting the app again brings the hidden window back.
• Updates. A build that knows its update manifest (see Updates) checks a minute after it starts and every six hours, quietly; a newer version brings a notification, and clicking it, or Help → Check for updates…, opens Wails' update window, which downloads the new binary, checks its SHA-256 (and signature, when the build pins a key), swaps it in and restarts.

Where things are kept

What	Where
The chosen homeserver, whether the tray hint was shown	desktop.json in the user config directory, under Warp (%AppData%\Warp on Windows, ~/Library/Application Support/Warp on macOS, ~/.config/Warp on Linux)
Sessions, encryption keys, cache	the webview's storage: %LocalAppData%\Warp\WebView2 on Windows; the platform webview's default location elsewhere

Signing out deletes a session's keys, the same as in the browser (see Encryption keys in the browser).

Build and run

Requires Go 1.26, Node 22 and pnpm. On Windows the WebView2 runtime, which Windows 11 ships with, and no C compiler. On macOS, Xcode's command line tools. On Linux, a C compiler with libgtk-4-dev and libwebkitgtk-6.0-dev (Wails needs cgo there, and builds against GTK 4 by default).

pnpm install
make desktop          # builds the web client, then bin/warp-desktop
./bin/warp-desktop

Flag	Environment
-homeserver	WARP_DESKTOP_HOMESERVER	use this homeserver for this run without saving it
-version		print the version

Command	What
make desktop	a release build: -tags production (no developer tools), and on Windows a GUI program with no console
make desktop-run	build the web client and run the app with the developer tools (View → Open Developer Tools)
make desktop-test	vet and test the Go code
make desktop-macos	on macOS: bin/Warp.app
make desktop-linux	on Linux: bin/warp-desktop.deb, .rpm and .pkg.tar.zst
make desktop-resources	regenerate the icons and the Windows .syso files
make desktop-windows-installer	on Windows, with NSIS: bin/warp-desktop-setup.exe
make desktop-manifest	the update manifest, bin/warp-desktop.json

A development build (one without -tags production) also opens the Chrome DevTools Protocol when WARP_DESKTOP_REMOTE_DEBUGGING_PORT is set, on Windows. A script or Playwright can then drive the real window:

WARP_DESKTOP_REMOTE_DEBUGGING_PORT=9229 go run ./cmd/warp-desktop

Packaging

The inputs are in build/. The wails3 CLI does the generating and the Linux packaging; the Makefile runs it with go run at the version go.mod pins (v3.0.0-beta.27), so it needs no install. DESKTOP_VERSION in the Makefile (default 0.1.0) is the version the OS sees in each package; -version prints the build's git version.

• Windows installer. make desktop-windows-installer turns the binary into bin/warp-desktop-setup.exe with NSIS (build/windows/installer.nsi). It installs for the current user, in %LocalAppData%\Programs\Warp with a Start menu entry and an entry in Installed apps, so it needs no administrator rights and the updater can replace the executable. It points at the WebView2 download when the runtime is missing. Uninstalling keeps your settings and the webview's storage, so a reinstall stays signed in. DESKTOP_SIGN signs the installer and uninstaller, given a signing command with %1 for the file.
• Windows. cmd/warp-desktop/rsrc_windows_{amd64,arm64}.syso carry the icon, the version info and the application manifest (per-monitor DPI, common controls 6, asInvoker). They are committed, so make desktop (and a plain go build) links them in with no extra step. The icon, build/windows/icon.ico, takes 16–48 px from the brand favicon (the symbol's small cut) and 64–256 px from the app icon tile; build/windows/mkico.go merges the two. After changing the icon, build/windows/info.json, the manifest or DESKTOP_VERSION, run make desktop-resources and commit the .syso files.
• macOS. make desktop-macos, on a Mac, builds the binary and puts it in bin/Warp.app with build/darwin/Info.plist and icons.icns, then signs the bundle ad hoc, and zips it as bin/Warp.app.zip for the updater. The Info.plist has NSCameraUsageDescription and NSMicrophoneUsageDescription: without them macOS ends the app the moment a call or the QR scanner asks for the camera or microphone. The bundle is for the CPU it was built on, and ad-hoc signed it opens only on the machine that built it; to hand it out, sign it with a Developer ID and notarize it.
• Linux. make desktop-linux, on Linux, builds the binary and turns it into .deb, .rpm and Arch packages with nfpm (through wails3 tool package, configured by build/linux/nfpm.yaml). They install /usr/bin/warp-desktop, a menu entry and the icon, and depend on GTK 4 and WebKitGTK 6.0 (Ubuntu 24.04+, Debian 13+, Fedora 40+). DESKTOP_FORMATS=deb builds one format; DESKTOP_MAINTAINER defaults to your git name and email.

build/appicon.png and build/windows/favicon.ico are copies from the brand kit (DESIGN/warp-brand/logo-kit, not in git): symbol/warp-symbol-app-icon-1024.png and web/favicon.ico.

Updates

The app updates itself from a Wails update manifest: one JSON document with the latest version and, per platform, the file to download and its SHA-256. Any static web server can host it, next to the files it lists.

• Build with DESKTOP_UPDATE_URL (the manifest's URL) and DESKTOP_VERSION (the version this build is, 1.2.3). A build without an update URL never checks, and has no Help menu.
• make desktop-manifest DESKTOP_VERSION=1.2.3 DESKTOP_ARTIFACTS="windows/amd64=bin/warp-desktop.exe ..." writes bin/warp-desktop.json; the artifact URLs are the files' names, relative to the manifest.
• Artifacts are the bare binaries for Windows and Linux, and Warp.app.zip for macOS. The Windows one is warp-desktop.exe, not the installer: the updater swaps the executable in place, which the per-user install allows. A Linux install from a package (in /usr) doesn't update itself; the package manager does that.
• DESKTOP_UPDATE_KEY, a PEM public key (Ed25519 or ECDSA P-256), makes the build insist on releases signed with its private key. Without one, a release is checked by its digest only, so the manifest's host is trusted.

The Desktop release workflow (.github/workflows/desktop-release.yml, on a desktop-v1.2.3 tag or by hand) builds Windows, Linux and macOS, the installer and the Linux packages, and writes the manifest; set the DESKTOP_UPDATE_URL repository variable to where you will publish them. It keeps everything as one workflow artifact; publishing is yours to do.

Layout

Path	What
cmd/warp-desktop/	the binary: the Wails app, window, menu and single-instance lock; notifications, the tray and the badge (desktop.go); updates (update.go)
internal/shell/	the webview's http.Handler: the client through apps/web/host, the first-run page and discovery, the settings file, links, the bridge the client's notifications and title go through
build/	packaging inputs: icons, the Windows manifest and version info, the NSIS installer script, Info.plist, the nfpm config; build/manifest, the update manifest writer

Not yet

These follow from PLAN.md §8.3:

• Signing, which needs certificates: an Authenticode-signed executable and installer (without it SmartScreen warns on first run), a Developer ID signed and notarized macOS .app in a .dmg (ad-hoc signed, it opens elsewhere only after "Open anyway"), and a signing key for update releases. The hooks are there: DESKTOP_SIGN, DESKTOP_UPDATE_KEY.
• A universal (arm64 + amd64) macOS build, an AppImage or Flatpak.
• Sync and encryption in Go (mautrix-go) behind the same Pinia stores, with the access token in the OS keychain. Today the desktop app runs matrix-js-sdk in the webview exactly as the browser does. Whether to move this to Go is open question 5 in the plan.