-[See desktop and mobile screenshots](docs/screenshots.md)
+[See screenshots](docs/screenshots.md)
## What
@@ -246,7 +246,7 @@ make doctor
There are a few similar tools in this space, and new ones appearing everyday. Here's what sets this one apart:
-- **Server-first architecture** - Not a desktop app. Runs as a server you can access from any device, including your phone. Start a task away from your computer and check in on it later.
+- **Server-first architecture** - The core app runs as a server you can access from any device, including your phone.
- **Remote runtimes** - Run agents on remote servers via SSH, Docker hosts, and cloud environments, not just your local machine.
- **Multi-provider** - Use Claude Code, Codex, Copilot, Gemini, Amp, Auggie, OpenCode, Cursor, Qwen, Droid, iFlow, Kilocode, Pi, Kimi, Kiro, Qoder, Trae, and Oh My Pi side by side. Not locked to one vendor.
- **CLI passthrough and chat** - Interact with agents through structured chat messages or drop into raw CLI mode for full agent TUI capabilities.
diff --git a/apps/backend/internal/backendapp/helpers.go b/apps/backend/internal/backendapp/helpers.go
index b5397a77c9..daab5b7e30 100644
--- a/apps/backend/internal/backendapp/helpers.go
+++ b/apps/backend/internal/backendapp/helpers.go
@@ -83,6 +83,11 @@ import (
ws "github.com/kandev/kandev/pkg/websocket"
)
+const (
+ desktopHealthTokenEnv = "KANDEV_DESKTOP_HEALTH_TOKEN"
+ desktopHealthTokenHeader = "X-Kandev-Desktop-Health-Token"
+)
+
// buildSessionDataProvider constructs the session data provider function used by the WebSocket hub
// to send initial data (git status, context window, available commands) when a client subscribes.
func buildSessionDataProvider(taskRepo *sqliterepo.Repository, lifecycleMgr *lifecycle.Manager, log *logger.Logger) func(context.Context, string) ([]*ws.Message, error) {
@@ -551,6 +556,9 @@ func registerRoutes(p routeParams) {
c.JSON(http.StatusServiceUnavailable, gin.H{"status": "starting", "service": "kandev"})
return
}
+ if token := desktopHealthToken(); token != "" {
+ c.Header(desktopHealthTokenHeader, token)
+ }
c.JSON(http.StatusOK, gin.H{"status": "ok", "service": "kandev", "mode": "websocket+http"})
})
@@ -614,6 +622,10 @@ func registerRoutes(p routeParams) {
}
}
+func desktopHealthToken() string {
+ return strings.TrimSpace(os.Getenv(desktopHealthTokenEnv))
+}
+
func newWebAppHandler(p routeParams) (*webapp.Handler, string, bool) {
assets, source, ok := webAssetsFS()
if !ok {
diff --git a/apps/backend/internal/backendapp/main.go b/apps/backend/internal/backendapp/main.go
index 767031cc1d..a869994ce8 100644
--- a/apps/backend/internal/backendapp/main.go
+++ b/apps/backend/internal/backendapp/main.go
@@ -12,6 +12,7 @@ import (
"os"
"os/signal"
"path/filepath"
+ "strings"
"sync/atomic"
"syscall"
"time"
@@ -740,21 +741,25 @@ func startGatewayAndServe(
// after we bind the socket above; probe the local listener with a short
// retry loop — once a single connect succeeds, the kernel queue is up and
// any subsequent /health call will land on a wired route.
- go waitListenerThenMarkReady(port, log)
+ go waitListenerThenMarkReady(server.Addr, log)
awaitShutdown(server, orchestratorSvc, lifecycleMgr, runCleanups, log)
return true
}
func startHTTPServer(server *http.Server, port int, log *logger.Logger) bool {
- ln, err := net.Listen("tcp", fmt.Sprintf(":%d", port))
+ addr := strings.TrimSpace(server.Addr)
+ if addr == "" {
+ addr = serverListenAddr("", port)
+ }
+ ln, err := net.Listen("tcp", addr)
if err != nil {
log.Error("Server listen error", zap.Error(err))
return false
}
go func() {
- log.Info("WebSocket server listening", zap.Int("port", port))
+ log.Info("WebSocket server listening", zap.String("addr", ln.Addr().String()), zap.Int("port", port))
if err := server.Serve(ln); err != nil && err != http.ErrServerClosed {
log.Error("Server serve error", zap.Error(err))
}
@@ -763,6 +768,26 @@ func startHTTPServer(server *http.Server, port int, log *logger.Logger) bool {
return true
}
+func serverListenAddr(host string, port int) string {
+ host = strings.TrimSpace(host)
+ if host == "" {
+ return fmt.Sprintf(":%d", port)
+ }
+ return net.JoinHostPort(host, fmt.Sprint(port))
+}
+
+func serverProbeAddr(listenAddr string) string {
+ host, port, err := net.SplitHostPort(listenAddr)
+ if err != nil {
+ return listenAddr
+ }
+ switch host {
+ case "", "0.0.0.0", "::":
+ host = "127.0.0.1"
+ }
+ return net.JoinHostPort(host, port)
+}
+
// waitListenerThenMarkReady probes the local HTTP listener until a
// connect succeeds, then flips the package-level `ready` flag so the
// /health handler stops returning 503. Runs in its own goroutine so
@@ -773,8 +798,8 @@ func startHTTPServer(server *http.Server, port int, log *logger.Logger) bool {
// of seconds. If the budget expires the flag still flips, so the
// backend doesn't permanently advertise "not ready" if probing fails
// for some unrelated reason (e.g. an iptables hiccup on a dev box).
-func waitListenerThenMarkReady(port int, log *logger.Logger) {
- addr := fmt.Sprintf("127.0.0.1:%d", port)
+func waitListenerThenMarkReady(listenAddr string, log *logger.Logger) {
+ addr := serverProbeAddr(listenAddr)
deadline := time.Now().Add(30 * time.Second)
ticker := time.NewTicker(50 * time.Millisecond)
defer ticker.Stop()
@@ -784,12 +809,12 @@ func waitListenerThenMarkReady(port int, log *logger.Logger) {
_ = conn.Close()
// A successful TCP dial proves the listener is bound.
ready.Store(true)
- log.Info("backend ready", zap.Int("port", port))
+ log.Info("backend ready", zap.String("addr", addr))
return
}
if time.Now().After(deadline) {
log.Warn("backend readiness probe never connected; flipping ready anyway",
- zap.Int("port", port))
+ zap.String("addr", addr))
ready.Store(true)
return
}
@@ -1630,7 +1655,7 @@ func buildHTTPServer(
})
return &http.Server{
- Addr: fmt.Sprintf(":%d", port),
+ Addr: serverListenAddr(cfg.Server.Host, port),
Handler: router,
ReadTimeout: cfg.Server.ReadTimeoutDuration(),
WriteTimeout: cfg.Server.WriteTimeoutDuration(),
diff --git a/apps/backend/internal/backendapp/server_test.go b/apps/backend/internal/backendapp/server_test.go
new file mode 100644
index 0000000000..ee8b4f1e14
--- /dev/null
+++ b/apps/backend/internal/backendapp/server_test.go
@@ -0,0 +1,107 @@
+package backendapp
+
+import (
+ "context"
+ "net"
+ "net/http"
+ "testing"
+
+ "github.com/kandev/kandev/internal/common/logger"
+ "go.uber.org/zap"
+)
+
+func TestStartHTTPServerUsesServerAddr(t *testing.T) {
+ log, err := logger.NewFromZap(zap.NewNop())
+ if err != nil {
+ t.Fatalf("NewFromZap: %v", err)
+ }
+
+ blocked := listenOnFreePort(t)
+ t.Cleanup(func() {
+ if err := blocked.Close(); err != nil {
+ t.Errorf("close blocked listener: %v", err)
+ }
+ })
+
+ server := &http.Server{
+ Addr: "127.0.0.1:0",
+ Handler: http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) { w.WriteHeader(http.StatusNoContent) }),
+ }
+ defer func() {
+ _ = server.Shutdown(context.Background())
+ }()
+
+ if !startHTTPServer(server, listenerPort(t, blocked), log) {
+ t.Fatalf("expected server to listen on configured Addr %q", server.Addr)
+ }
+}
+
+func TestServerListenAddr(t *testing.T) {
+ tests := []struct {
+ name string
+ host string
+ port int
+ want string
+ }{
+ {name: "blank host keeps port-only address", host: "", port: 38429, want: ":38429"},
+ {name: "wildcard host", host: "0.0.0.0", port: 38429, want: "0.0.0.0:38429"},
+ {name: "loopback host", host: "127.0.0.1", port: 38429, want: "127.0.0.1:38429"},
+ {name: "ipv6 host", host: "::1", port: 38429, want: "[::1]:38429"},
+ }
+
+ for _, tt := range tests {
+ t.Run(tt.name, func(t *testing.T) {
+ if got := serverListenAddr(tt.host, tt.port); got != tt.want {
+ t.Fatalf("serverListenAddr(%q, %d) = %q, want %q", tt.host, tt.port, got, tt.want)
+ }
+ })
+ }
+}
+
+func TestDesktopHealthTokenTrimsEnv(t *testing.T) {
+ t.Setenv(desktopHealthTokenEnv, " token-value ")
+
+ if got := desktopHealthToken(); got != "token-value" {
+ t.Fatalf("desktopHealthToken() = %q, want token-value", got)
+ }
+}
+
+func TestServerProbeAddr(t *testing.T) {
+ tests := []struct {
+ name string
+ listenAddr string
+ want string
+ }{
+ {name: "port-only address probes loopback", listenAddr: ":38429", want: "127.0.0.1:38429"},
+ {name: "wildcard ipv4 probes loopback", listenAddr: "0.0.0.0:38429", want: "127.0.0.1:38429"},
+ {name: "wildcard ipv6 probes loopback", listenAddr: "[::]:38429", want: "127.0.0.1:38429"},
+ {name: "loopback address probes itself", listenAddr: "127.0.0.1:38429", want: "127.0.0.1:38429"},
+ {name: "ipv6 loopback probes itself", listenAddr: "[::1]:38429", want: "[::1]:38429"},
+ }
+
+ for _, tt := range tests {
+ t.Run(tt.name, func(t *testing.T) {
+ if got := serverProbeAddr(tt.listenAddr); got != tt.want {
+ t.Fatalf("serverProbeAddr(%q) = %q, want %q", tt.listenAddr, got, tt.want)
+ }
+ })
+ }
+}
+
+func listenOnFreePort(t *testing.T) net.Listener {
+ t.Helper()
+ ln, err := net.Listen("tcp", "127.0.0.1:0")
+ if err != nil {
+ t.Fatalf("listen on free port: %v", err)
+ }
+ return ln
+}
+
+func listenerPort(t *testing.T, ln net.Listener) int {
+ t.Helper()
+ tcpAddr, ok := ln.Addr().(*net.TCPAddr)
+ if !ok {
+ t.Fatalf("expected TCP listener, got %T", ln.Addr())
+ }
+ return tcpAddr.Port
+}
diff --git a/apps/backend/internal/common/config/config_test.go b/apps/backend/internal/common/config/config_test.go
index c6a2ef73cb..bf38b4884b 100644
--- a/apps/backend/internal/common/config/config_test.go
+++ b/apps/backend/internal/common/config/config_test.go
@@ -187,6 +187,18 @@ func TestFeatures_OfficeEnabledByEnv(t *testing.T) {
}
}
+func TestServerHostFromEnv(t *testing.T) {
+ t.Setenv("KANDEV_SERVER_HOST", "127.0.0.1")
+
+ cfg, err := LoadWithPath(t.TempDir())
+ if err != nil {
+ t.Fatalf("LoadWithPath: %v", err)
+ }
+ if cfg.Server.Host != "127.0.0.1" {
+ t.Fatalf("Server.Host = %q, want 127.0.0.1", cfg.Server.Host)
+ }
+}
+
// TestFeaturesConfig_JSONShape pins the wire format of GET /api/v1/features.
// The handler in helpers.go serializes FeaturesConfig directly so new
// fields flow through without an extra edit; this test guarantees the
diff --git a/apps/cli/README_internal.md b/apps/cli/README_internal.md
index 796f338c1b..ad1e8028cd 100644
--- a/apps/cli/README_internal.md
+++ b/apps/cli/README_internal.md
@@ -47,9 +47,14 @@ kandev/
# npm runtime package (@kdlbs/runtime-{platform})
@kdlbs/runtime-{platform}/
└── bin/{kandev,agentctl,agentctl-linux-amd64}
+
+# Tauri desktop resource directory
+apps/desktop/src-tauri/resources/kandev/
+└── bin/{kandev[.exe],agentctl[.exe],agentctl-linux-amd64}
```
For npm installs, the main `kandev` package provides only a tiny Node bin shim that execs `bin/kandev` from the platform runtime package.
+For desktop release builds, `scripts/release/prepare-desktop-runtime.sh` extracts the matching GitHub release bundle into the Tauri resource directory before `tauri build` runs.
## Commands
@@ -121,9 +126,9 @@ Releases run entirely in GitHub Actions. From the GHA UI:
4. Optionally tick `dry_run` to validate without publishing.
5. Click **Run workflow**.
-The workflow does everything: version bump, CHANGELOG, PR, merge, tag, build, npm publish, Homebrew tap update. See [/.github/workflows/release.yml](../../.github/workflows/release.yml).
+The workflow does everything: version bump, CHANGELOG, PR, merge, tag, runtime bundles, desktop artifacts, npm publish, Homebrew tap update. See [/.github/workflows/release.yml](../../.github/workflows/release.yml).
-Single SemVer flow: `apps/cli/package.json` version, git tag, npm packages, and Homebrew formula are all bumped to the same `X.Y.Z`.
+Single SemVer flow: `apps/cli/package.json` version, git tag, npm packages, Homebrew formula, GitHub runtime tarballs, and desktop artifacts are all bumped to the same `X.Y.Z`.
Versioning:
diff --git a/apps/cli/src/release-config.test.ts b/apps/cli/src/release-config.test.ts
index 3272086e34..dd21ee8e02 100644
--- a/apps/cli/src/release-config.test.ts
+++ b/apps/cli/src/release-config.test.ts
@@ -181,3 +181,133 @@ describe("release npm publishing", () => {
expect(script).toContain("treated as idempotent success");
});
});
+
+describe("release desktop artifacts", () => {
+ const desktopPlatforms = ["macos-arm64", "macos-x64", "linux-x64", "linux-arm64", "windows-x64"];
+
+ function releaseWorkflow(): string {
+ return readRepoFile(".github/workflows/release.yml");
+ }
+
+ it("builds desktop artifacts for every supported runtime platform", () => {
+ const workflow = releaseWorkflow();
+
+ expect(workflow).toMatch(/\n build-desktop:\n/);
+ expect(workflow).toContain("needs: [prepare, build-bundles]");
+ expect(workflow).toContain("scripts/release/prepare-desktop-runtime.sh");
+ expect(workflow).toContain('--platform "${{ matrix.platform }}"');
+ expect(workflow).toContain(
+ 'rustup toolchain install stable --profile minimal --target "${{ matrix.rust_target }}"',
+ );
+ expect(workflow).toContain("Swatinem/rust-cache@v2");
+
+ for (const platform of desktopPlatforms) {
+ expect(workflow, `release.yml must include desktop platform ${platform}`).toContain(
+ `platform: ${platform}`,
+ );
+ }
+ });
+
+ it("publishes desktop artifacts while leaving npm and Homebrew tied to runtime tarballs", () => {
+ const workflow = releaseWorkflow();
+ const publishNpmScript = readRepoFile("scripts/release/publish-npm.sh");
+ const homebrewScript = readRepoFile("scripts/release/update-homebrew-tap.sh");
+
+ expect(workflow).toContain(
+ "needs: [prepare, build-bundles, build-desktop, docker-universal-manifest]",
+ );
+ expect(workflow).toContain("pattern: desktop-*");
+ expect(workflow).toContain("scripts/release/verify-desktop-assets.sh");
+ expect(workflow).toContain("dist/release-assets/kandev-desktop-*");
+ expect(workflow).toContain('shasum -a 256 "$(basename "$dest")"');
+
+ expect(publishNpmScript).toContain('asset="kandev-${platform}.tar.gz"');
+ expect(publishNpmScript).not.toContain("kandev-desktop-");
+ expect(homebrewScript).toContain('local sha_file="kandev-${platform}.tar.gz.sha256"');
+ expect(homebrewScript).not.toContain("kandev-desktop-");
+ });
+
+ it("bumps desktop package and Tauri versions during release preparation", () => {
+ const workflow = releaseWorkflow();
+
+ expect(workflow).toContain('(cd apps/desktop && npm version --no-git-tag-version "$NEXT")');
+ expect(workflow).toContain("tauriConfig.version = next");
+ expect(workflow).toContain('cargoToml.replace(/^version = ".*"$/m, `version = "${next}"`)');
+ expect(workflow).toContain('name = "kandev-desktop"');
+ expect(workflow).toContain("apps/desktop/src-tauri/tauri.conf.json");
+ expect(workflow).toContain("apps/desktop/src-tauri/Cargo.toml");
+ expect(workflow).toContain("apps/desktop/src-tauri/Cargo.lock");
+ });
+
+ it("pins linux x64 desktop release builds to Ubuntu 22.04", () => {
+ const workflow = releaseWorkflow();
+
+ expect(workflow).toContain(`- os: ubuntu-22.04
+ platform: linux-x64
+ goos: linux
+ goarch: amd64`);
+ expect(workflow).toContain(`- platform: linux-x64
+ os: ubuntu-22.04
+ rust_target: x86_64-unknown-linux-gnu
+ tauri_bundles: deb,rpm`);
+ });
+
+ it("fails public macOS and Windows desktop builds closed when signing secrets are absent", () => {
+ const workflow = releaseWorkflow();
+ const signingDocs = readRepoFile("docs/desktop-tauri-signing.md");
+ const tauriConfig = readRepoFile("apps/desktop/src-tauri/tauri.conf.json");
+ const windowsSignScript = readRepoFile("apps/desktop/src-tauri/windows-sign.ps1");
+
+ expect(workflow).toContain("allow_unsigned_desktop");
+ expect(workflow).toContain("Unsigned desktop artifacts are internal validation only");
+ expect(workflow).toContain("ref: ${{ needs.prepare.outputs.ref }}");
+ expect(workflow).toContain("persist-credentials: false");
+ expect(workflow).toContain("Unsigned desktop validation summary");
+ expect(workflow).toContain("No release PR, tag, GitHub release, public container tags");
+ expect(workflow).toContain("if: ${{ !inputs.dry_run && !inputs.allow_unsigned_desktop }}");
+ expect(workflow).toContain("docker-amd64:");
+ expect(workflow).toContain("docker-universal-manifest:");
+
+ for (const key of [
+ "APPLE_CERTIFICATE",
+ "APPLE_CERTIFICATE_PASSWORD",
+ "KEYCHAIN_PASSWORD",
+ "APPLE_SIGNING_IDENTITY",
+ "APPLE_API_KEY_P8",
+ "APPLE_API_KEY_PATH",
+ "APPLE_TEAM_ID",
+ ]) {
+ expect(workflow, `release.yml must wire ${key}`).toContain(key);
+ }
+
+ for (const key of ["WINDOWS_CERTIFICATE", "WINDOWS_CERTIFICATE_PASSWORD", "signtool sign"]) {
+ expect(workflow, `release.yml must wire ${key}`).toContain(key);
+ }
+ expect(workflow).toContain("Invoke-SignTool");
+ expect(workflow).toContain("$LASTEXITCODE -ne 0");
+ expect(workflow).toContain("Sign macOS desktop runtime binaries");
+ expect(workflow).toContain("resources/kandev/bin");
+ expect(workflow).toContain("for binary in kandev agentctl; do");
+ expect(workflow).toContain(
+ 'codesign --force --options runtime --timestamp --sign "$APPLE_SIGNING_IDENTITY"',
+ );
+ expect(workflow).toContain("codesign --verify --strict");
+ expect(workflow).toContain("Sign Windows desktop runtime binaries");
+ expect(workflow).toContain('foreach ($binary in @("kandev.exe", "agentctl.exe"))');
+ expect(workflow).toContain("Remove-Item -LiteralPath $certificatePath");
+
+ expect(tauriConfig).toContain('"publisher": "Kandev"');
+ expect(tauriConfig).toContain('"timestampUrl"');
+ expect(tauriConfig).toContain('"timestampUrl": "https://timestamp.digicert.com"');
+ expect(tauriConfig).toContain('"signCommand"');
+ expect(tauriConfig).toContain("windows-sign.ps1");
+ expect(tauriConfig).not.toContain('"csp": null');
+ expect(windowsSignScript).toContain('"https://timestamp.digicert.com"');
+ expect(windowsSignScript).toContain("Remove-Item -LiteralPath $certificatePath");
+ expect(signingDocs).toContain("Public recommended desktop releases require signing");
+ expect(signingDocs).toContain("allow_unsigned_desktop");
+ expect(signingDocs).toContain("does not publish a GitHub release");
+ expect(signingDocs).toContain("public container tags");
+ expect(signingDocs).toContain("Ubuntu 22.04");
+ });
+});
diff --git a/apps/desktop/AGENTS.md b/apps/desktop/AGENTS.md
new file mode 100644
index 0000000000..595207e3c2
--- /dev/null
+++ b/apps/desktop/AGENTS.md
@@ -0,0 +1,35 @@
+# Desktop App Guidance
+
+`apps/desktop` is the Tauri v2 shell for Kandev. It should stay a thin desktop wrapper over the existing native runtime and Go-served SPA.
+
+## Commands
+
+Run from `apps/` unless noted:
+
+- `pnpm --filter @kandev/desktop build:vite` builds the startup surface.
+- `pnpm --filter @kandev/desktop build` builds the Linux desktop bundle locally.
+- `pnpm --filter @kandev/desktop e2e` builds the app and runs the Linux smoke harness under Xvfb when needed.
+- From `apps/desktop/src-tauri`, `cargo test` runs Rust unit tests without requiring the Tauri runtime feature by default.
+
+## Runtime Resources
+
+Release builds prepare `src-tauri/resources/kandev/` with:
+
+```text
+bin/kandev[.exe]
+bin/agentctl[.exe]
+bin/agentctl-linux-amd64
+```
+
+Use `scripts/release/prepare-desktop-runtime.sh` and `scripts/release/verify-desktop-runtime.sh`; do not commit runtime binaries. The tracked `.gitignore` files only keep the resource directory present for Tauri config validation.
+
+## Architecture
+
+- Frontend code in `src/` is only the startup/error surface. The real product UI is still served by the Go backend after `/health` succeeds.
+- Rust code owns backend process spawning and cleanup. Do not expose broad shell or filesystem permissions to frontend JavaScript.
+- Desktop launches force `KANDEV_SERVER_HOST=127.0.0.1`, prefer a stable desktop port with random fallback, and pass `KANDEV_BUNDLE_DIR` to the native launcher.
+- `KANDEV_DESKTOP_RUNTIME_DIR` is a test/development override for runtime resources.
+
+## Release
+
+Desktop artifacts are built in `.github/workflows/release.yml` after the platform runtime bundles. Public macOS and Windows artifacts require signing unless `allow_unsigned_desktop=true` is explicitly selected for internal validation.
diff --git a/apps/desktop/e2e/README.md b/apps/desktop/e2e/README.md
new file mode 100644
index 0000000000..382eb1c819
--- /dev/null
+++ b/apps/desktop/e2e/README.md
@@ -0,0 +1,5 @@
+# Desktop E2E
+
+`pnpm --filter @kandev/desktop e2e` builds the Linux desktop bundle, launches the compiled Tauri app under `xvfb-run` when no display is available, and points it at a fake native runtime.
+
+The fake runtime exposes `/health` and `/`. The smoke test passes only after the WebView requests `/`, which proves the startup screen transitioned to the backend UI after health succeeded.
diff --git a/apps/desktop/e2e/desktop-launch-smoke.mjs b/apps/desktop/e2e/desktop-launch-smoke.mjs
new file mode 100644
index 0000000000..3bdcbe5882
--- /dev/null
+++ b/apps/desktop/e2e/desktop-launch-smoke.mjs
@@ -0,0 +1,186 @@
+#!/usr/bin/env node
+import { createServer } from "node:http";
+import { chmod, mkdir, mkdtemp, writeFile } from "node:fs/promises";
+import { existsSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { delimiter, dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { spawn } from "node:child_process";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const desktopRoot = resolve(__dirname, "..");
+const repoRoot = resolve(desktopRoot, "../..");
+
+if (process.argv[2] === "--fake-runtime") {
+ await runFakeRuntime(process.argv[3], process.argv.slice(4));
+} else {
+ await runSmoke();
+}
+
+async function runSmoke() {
+ const appBinary = resolve(desktopRoot, "src-tauri/target/release/kandev-desktop");
+ if (!existsSync(appBinary)) {
+ throw new Error(`Missing desktop binary at ${appBinary}; run pnpm build first`);
+ }
+
+ const tmp = await mkdtemp(join(tmpdir(), "kandev-desktop-e2e-"));
+ const runtimeDir = join(tmp, "runtime");
+ const stateDir = join(tmp, "state");
+ await mkdir(join(runtimeDir, "bin"), { recursive: true });
+ await mkdir(stateDir, { recursive: true });
+
+ await writeFakeRuntime(runtimeDir, stateDir);
+
+ const launchedViaXvfb = !process.env.DISPLAY && commandExists("xvfb-run");
+ const command = launchedViaXvfb ? "xvfb-run" : appBinary;
+ const args = launchedViaXvfb ? ["-a", appBinary] : [];
+ const child = spawn(command, args, {
+ cwd: repoRoot,
+ detached: process.platform !== "win32",
+ env: {
+ ...process.env,
+ KANDEV_DESKTOP_RUNTIME_DIR: runtimeDir,
+ WEBKIT_DISABLE_COMPOSITING_MODE: "1",
+ NO_AT_BRIDGE: "1",
+ },
+ stdio: ["ignore", "pipe", "pipe"],
+ });
+
+ let stdout = "";
+ let stderr = "";
+ child.stdout?.on("data", (chunk) => {
+ stdout += chunk;
+ });
+ child.stderr?.on("data", (chunk) => {
+ stderr += chunk;
+ });
+
+ const failIfExited = () => {
+ if (child.exitCode !== null) {
+ throw new Error(`desktop app exited early with code ${child.exitCode}\n${stdout}\n${stderr}`);
+ }
+ };
+
+ try {
+ await waitForFile(join(stateDir, "health-requested"), 45_000, failIfExited);
+ await waitForFile(join(stateDir, "root-requested"), 45_000, failIfExited);
+ } finally {
+ await stopProcess(child);
+ }
+
+ console.log("Desktop smoke passed: WebView requested / after backend health succeeded.");
+}
+
+async function writeFakeRuntime(runtimeDir, stateDir) {
+ const fakeRuntime = join(runtimeDir, "bin", process.platform === "win32" ? "kandev.cmd" : "kandev");
+ const agentctl = join(runtimeDir, "bin", process.platform === "win32" ? "agentctl.cmd" : "agentctl");
+ const linuxHelper = join(runtimeDir, "bin", "agentctl-linux-amd64");
+
+ if (process.platform === "win32") {
+ await writeFile(
+ fakeRuntime,
+ `@echo off\r\nnode "${fileURLToPath(import.meta.url)}" --fake-runtime "${stateDir}" %*\r\n`,
+ );
+ await writeFile(agentctl, "@echo off\r\necho fake agentctl\r\n");
+ } else {
+ await writeFile(
+ fakeRuntime,
+ `#!/usr/bin/env bash\nexec node "${fileURLToPath(import.meta.url)}" --fake-runtime "${stateDir}" "$@"\n`,
+ );
+ await writeFile(agentctl, "#!/usr/bin/env bash\necho fake agentctl\n");
+ await chmod(fakeRuntime, 0o755);
+ await chmod(agentctl, 0o755);
+ }
+
+ await writeFile(linuxHelper, "#!/usr/bin/env bash\necho fake agentctl linux helper\n");
+ if (process.platform !== "win32") {
+ await chmod(linuxHelper, 0o755);
+ }
+}
+
+async function runFakeRuntime(stateDir, args) {
+ const portIndex = args.indexOf("--port");
+ const port = portIndex >= 0 ? Number(args[portIndex + 1]) : 0;
+ const isHeadless = args.includes("--headless");
+
+ if (!isHeadless || !Number.isInteger(port) || port <= 0) {
+ await writeFile(join(stateDir, "invalid-args"), JSON.stringify(args));
+ process.exit(2);
+ }
+
+ await writeFile(join(stateDir, "launched"), JSON.stringify({ args, port }));
+
+ const server = createServer(async (req, res) => {
+ if (req.url === "/health") {
+ await writeFile(join(stateDir, "health-requested"), "1");
+ const headers = { "content-type": "application/json" };
+ if (process.env.KANDEV_DESKTOP_HEALTH_TOKEN) {
+ headers["x-kandev-desktop-health-token"] = process.env.KANDEV_DESKTOP_HEALTH_TOKEN;
+ }
+ res.writeHead(200, headers);
+ res.end('{"status":"ok"}');
+ return;
+ }
+
+ if (req.url === "/") {
+ await writeFile(join(stateDir, "root-requested"), "1");
+ res.writeHead(200, { "content-type": "text/html" });
+ res.end("Kandev
+Preparing the local runtime and opening your workspace.
+