Files

T

Carlos Florêncio 14a5fb2c7f fix: support unsigned desktop releases (#1520 )

2026-06-28 19:13:16 +01:00

11 KiB

Raw Blame History

status, created, owner

status	created	owner
implemented	2026-06-23	tbd

Tauri Desktop App

Why

Users who prefer a desktop workflow should be able to install and open Kandev from the OS app launcher without running a terminal command or managing a browser tab. The installed desktop app should keep Kandev's current local-first behavior while avoiding a production Node.js runtime.

What

Kandev provides desktop installers for the same primary release platforms as the native runtime bundle: macOS arm64, macOS x64, Linux x64, Linux arm64, and Windows x64.
Opening the desktop app starts a local Kandev backend and displays the existing Vite/React Kandev UI inside a native Tauri WebView window.
The installed desktop app does not require Node.js. Node.js and pnpm remain build-time tooling in CI and local development only.
The desktop app reuses the existing Go-served SPA with embedded Vite assets. It does not ship or start a separate web server.
The desktop app reuses the existing Kandev data directory, SQLite database, worktrees, executor settings, integrations, and agent configuration.
The desktop app owns the backend lifecycle for the process it starts: startup waits for /health, normal quit terminates child processes, and startup failure surfaces an error instead of leaving orphaned backend processes.
The desktop app starts the backend on a loopback-only address and an available local port unless the user has explicitly configured otherwise through existing environment/config mechanisms.
The desktop app launches the backend with a predictable process environment for GUI launches, including common user binary locations, so configured agent CLIs can be discovered as reliably as they are from terminal-launched Kandev.
Opening a second desktop instance focuses the existing app window or exits without starting a second backend for the same desktop launch context.
GitHub releases include desktop artifacts alongside the existing runtime tarballs and checksums.
Unsigned desktop artifacts may be produced only through explicit development, validation, or release workflow overrides. Public recommended desktop releases require macOS Developer ID signing/notarization and Windows code signing before they are presented as trusted user-facing downloads.
Desktop release notes and install docs tell users which artifact to download for each operating system and call out any unsigned/pre-release limitations.

Data model

The feature does not add backend database tables.

Desktop runtime state is process-local except for optional window placement/state stored by Tauri under the OS application data location. Kandev user data remains owned by the existing backend persistence model under KANDEV_HOME_DIR or the default ~/.kandev location.

API surface

Desktop launch contract

The Tauri shell starts the packaged native Kandev launcher in headless mode with an explicit backend port:

kandev --headless --port <available-loopback-port>

The launcher starts the backend through the existing hidden backend mode and keeps the supervisor process alive until the desktop app exits. The desktop shell polls:

GET http://127.0.0.1:<port>/health

Desktop launches pass a per-launch KANDEV_DESKTOP_HEALTH_TOKEN to the native launcher environment. The backend echoes the token in the X-Kandev-Desktop-Health-Token response header on successful /health responses. The desktop shell treats /health as ready only when the status is successful and the response header matches its generated token, so a separate local process on the same loopback port cannot satisfy desktop readiness.

When /health reports ready for that launch, the desktop window navigates to:

http://127.0.0.1:<port>/

Backend bind contract

Desktop launches set the backend host to loopback:

KANDEV_SERVER_HOST=127.0.0.1

The backend server honors server.host / KANDEV_SERVER_HOST when binding its listener. Existing CLI and service launches may keep their current default unless explicitly changed by their own specs.

Desktop environment contract

The desktop shell passes an explicit environment to the native launcher:

Existing user environment variables are preserved when available.
KANDEV_SERVER_HOST=127.0.0.1 is set for desktop launches.
PATH includes common GUI-missing user binary locations such as /usr/local/bin, /opt/homebrew/bin, /usr/bin, /bin, %USERPROFILE%/.local/bin, and existing Kandev agent CLI install locations where applicable.
Explicit agent command paths configured in Kandev settings remain authoritative over PATH lookup.

Desktop artifact contract

Each released version includes platform desktop artifacts with checksums. Exact file names may follow Tauri's generated naming, but the release must expose these platform groups:

macOS arm64: signed/notarized .dmg for recommended public release, unsigned .dmg allowed only through an explicit override.
macOS x64: signed/notarized .dmg for recommended public release, unsigned .dmg allowed only through an explicit override.
Windows x64: signed installer (.exe or .msi) for recommended public release, unsigned installer allowed only through an explicit override.
Linux x64: AppImage and/or distro package generated by Tauri, with checksum.
Linux arm64: AppImage and/or distro package generated by Tauri, with checksum.

Existing backend API

The desktop app uses the existing backend HTTP, WebSocket, and boot-payload contracts. No new product API is required for the main Kandev UI.

State machine

Desktop app lifecycle:

idle: the app process has started but no backend child is running.
backend-starting: the app has spawned the native launcher and is polling backend health.
ready: the backend is healthy and the WebView is displaying the Kandev UI.
backend-restarting: the launcher supervisor is replacing the backend child after an existing restart request.
stopping: the user quit the app or the app is terminating its child processes.
failed: startup failed before the UI became ready.

Transitions:

idle -> backend-starting: user opens the desktop app.
backend-starting -> ready: /health returns success and the WebView navigates to the backend URL.
backend-starting -> failed: the launcher exits, a required bundled binary is missing, the backend cannot bind, or health times out.
ready -> backend-restarting: the existing backend restart supervisor handles a restart request.
backend-restarting -> ready: the replacement backend becomes healthy on the same launch URL.
any active state -> stopping: the user quits the app or the OS terminates the app.
stopping -> idle: child processes are terminated and the app exits.

Permissions

The desktop app runs with the current OS user's permissions and does not require administrator/root privileges for normal install or launch.
Backend filesystem, Docker, SSH, Git, and credential access remains governed by existing Kandev backend and executor behavior.
The WebView does not receive broad shell/filesystem permissions. Process spawning for the backend is owned by the Tauri Rust side, not by arbitrary frontend code.
Signing credentials are CI secrets. They are never committed to the repository or exposed to the desktop app runtime.

Failure modes

Missing packaged kandev, agentctl, or required helper binaries cause startup to fail with a visible desktop error that names the missing artifact.
If the selected backend port is unavailable, the desktop app chooses a different available port before launch. If no port can be selected, startup fails visibly.
If the backend exits before /health succeeds, the desktop app shows a startup failure and includes the captured launcher/backend output when available.
If /health does not succeed before the configured timeout, the desktop app terminates the launched child process tree and shows a timeout error.
If the WebView runtime is unavailable or broken on the host OS, the app fails using the platform's normal Tauri/WebView error behavior; the backend process must not remain running.
If an agent CLI cannot be found from a GUI-launched environment, the desktop app/backend surfaces the same setup-health guidance as browser/CLI Kandev rather than failing silently.
If signing/notarization secrets are absent in CI, release automation may still build explicitly unsigned desktop artifacts, but trusted desktop artifacts are not marked complete.

Persistence guarantees

Kandev data created through the desktop app survives app quit and process restart using the same persistence guarantees as CLI-launched Kandev.
In-flight backend process state does not survive app quit. On next launch, the desktop app starts a fresh backend process, and backend recovery follows existing Kandev recovery behavior.
Optional window size/position persistence survives app restart if the Tauri window-state plugin is enabled.
Desktop installer artifacts do not alter existing npm/Homebrew/manual runtime update semantics.

Scenarios

GIVEN Kandev is installed as a desktop app on a machine without Node.js, WHEN the user opens the app, THEN the backend starts and the Kandev UI appears in the desktop window.
GIVEN the desktop app is already running, WHEN the user opens the app again, THEN the existing window is focused and no second backend is started for that desktop app instance.
GIVEN the backend has not finished startup, WHEN the desktop app is open, THEN the user sees a startup/loading state until /health succeeds or startup fails.
GIVEN the backend becomes healthy, WHEN the desktop app navigates to the backend URL, THEN the existing Kandev boot payload hydrates the UI without a separate Node.js web runtime.
GIVEN an agent CLI is installed in a common user binary location but the desktop app was opened from the OS launcher, WHEN the user starts a session using that agent, THEN Kandev can discover the agent command or surfaces existing setup-health guidance.
GIVEN the user quits the desktop app, WHEN the app exits normally, THEN the launcher/backend child process tree is terminated.
GIVEN a bundled backend binary is missing, WHEN the user opens the desktop app, THEN startup fails with a visible error naming the missing binary.
GIVEN the release workflow builds desktop artifacts for a version, WHEN the GitHub release is published, THEN desktop installers and checksums are attached alongside the existing runtime tarballs.
GIVEN a recommended public macOS desktop release, WHEN the user downloads and opens the .dmg, THEN the app is signed and notarized so macOS does not report the download as damaged or from an unidentified developer.
GIVEN a recommended public Windows desktop release, WHEN the user runs the installer, THEN the installer is code signed to reduce SmartScreen trust warnings.

Out of scope

Replacing the existing npm, Homebrew, Docker, or runtime tarball channels.
Requiring npx or npm installs to be Node-free.
Mobile Tauri targets.
App Store, Microsoft Store, Snapcraft, AUR, or Homebrew Cask distribution.
In-app Tauri updater support in the first desktop release.
Running Kandev as a background tray app after all windows close.
Rewriting the Kandev frontend or backend in Rust.

11 KiB Raw Blame History