Troubleshoot the Desktop app

Start with the symptom below. Keep the verified v2.19.0 artifact and preserve AgentKit state while you diagnose the issue.

The window does not open

On Linux, the AppImage is currently verified on Debian and Ubuntu. On Fedora, Arch, and other distributions that install WebKit's helper processes in a different location, the window can still fail to open with the 4.1 runtime installed; see Installation. If your runtime is installed in a working layout that the preflight check does not recognize, set AK_GUI_SKIP_WEBKIT_PREFLIGHT=1 to launch anyway. Skipping the check does not fix a missing runtime; the launch can still abort.

Desktop requires a graphical session. --no-interactive does not suppress the window, and --json and --quiet do not create a structured or silent launch. For a headless host, use CLI commands or start the separate browser dashboard without opening a local browser:

ak config start --no-open

Expose that server beyond its default loopback bind only after applying the appropriate authentication and network controls.

Desktop remains on the license screen

A successful CLI login does not activate Desktop. Enter a valid App license in Desktop while online. If the 72-hour offline grace period has expired, reconnect so Desktop can verify it again. A message that this device was signed out of the license, or that the license is no longer active, is a registry decision; activate again with the license key or contact support.

If activation reports that the device limit is reached, a single-seat license moves to this device automatically and a full multi-seat license offers Move the license to this device. ak login --license-key does not move seats, so use Desktop for that choice.

If Desktop reports that it cannot read or save the session, inspect ownership and permissions of $AGENTKIT_HOME/auth/session.json. Do not paste the file into a support request and do not delete the whole AgentKit home. Profile → Sign out clears only the local App slot; ak logout clears only the CLI slot.

Kits, Activity, or Sessions look empty

• Refresh the App session and network connection when the entitled Kit catalog is unavailable. A Kit appears installable only when the App session grants it.
• Rerun the local scan when a newly installed coding assistant or registered project is missing. After installing a Kit, restart that assistant or open a new runtime session.
• Activity reads $AGENTKIT_HOME/activity/events.ndjson. Sessions reconcile supported Claude Code and Codex sources into $AGENTKIT_HOME/analytics/analytics.db while Desktop is open. An empty view can mean there is no supported local evidence yet; it does not prove files were deleted.
• Desktop sets up the local analytics index on its own and rebuilds one it can no longer open, unless you disabled or deleted the index. After a disable or delete, switch Use local index back on in the Settings Database tab or run ak analytics enable. Use Sync now in that tab to refresh it.
• Removing a project in Desktop removes only its AgentKit registry entry. It does not delete the project directory.

If onboarding reports that Node.js is missing, use its explicit Node.js LTS installation action or the displayed manual hint. Wait for the version recheck, then rerun the affected Kit install or refresh so Node-backed Hooks and status lines can be configured.

Desktop v2.19.0 does not launch Kit skills or agent runs. Run the skill in its coding assistant before expecting new Activity or session evidence.

A port is busy

Desktop itself binds no HTTP port. A conflict on 127.0.0.1:8766 belongs to the separately started browser dashboard; a conflict on 127.0.0.1:8765 belongs to the separately started API server. Check those processes with:

ak config status
ak api status

Closing Desktop stops its in-process services, streams, and reconciler, but it does not stop a dashboard or API server started separately.

An update will not complete

• Windows x64 stages the matching CLI and Desktop artifacts, then a trusted handoff helper commits the swap after the parent process releases the executables. If that cannot complete, download and verify the replacement Desktop zip manually.
• On macOS or Linux x64, keep the matching standard CLI installed and preserve $AGENTKIT_HOME/updater/pending-binary-update.json plus its reported staging directory.
• Free disk space, fix ownership or permissions, close processes holding the executable, then reopen the same Desktop app to retry.
• If rollback also failed, stop. Preserve the installed, staged, pending, and backup paths from the error instead of manually swapping files.

Read Update the Desktop app for the transaction boundary and the ak self-update reference for CLI output and exit behavior.

Capture safe diagnostics

Quit Desktop, open a terminal, and launch the exact installed executable:

/Applications/agentkit.app/Contents/MacOS/ak-gui

./ak-gui_2.19.0_linux_amd64.AppImage

.\ak-gui.exe

Desktop runtime, update, and launch diagnostics can appear as plain text on stderr. On Windows, Desktop also writes a launch log to %LOCALAPPDATA%\agentkit\logs\ak-gui.log. A windowless launch failure shows a native dialog with the error and log location; a missing WebView2 runtime also includes the official repair link. For another startup failure, check Event Viewer → Windows Logs → Application for an ak-gui.exe entry while keeping endpoint protection enabled.

Record the symptom, operating system, architecture, artifact name, SHA-256 result, and only the relevant stderr, log, or Event Viewer lines. Remove license keys, session content, private project paths, and unmasked configuration values before sharing diagnostics.

Reinstalling the same verified Desktop package can replace the app without removing AgentKit data. Delete only the installed app item described in Installation, never the entire AgentKit or runtime home.