Troubleshooting & FAQ

Settings, Diagnostics is a read-only snapshot of everything a support answer needs: the Deska version and release channel, the Electron, Chromium, Node and V8 versions, your platform and kernel, the six paths on disk that matter, from the application data folder to the agent worktrees (each with a Reveal button so you can open them), the last cached probe for every coding-agent instance, and the size of the agent thread log.

Copy diagnostics copies all of it as plain text. It carries no account names, tokens or API keys, so it is safe to paste into an email or an issue. Attaching it turns most back-and-forth into a single reply.

Dex runs on your own coding agent (Claude Code, Codex or opencode), signed in to Deska or not, so the checks are about the engine rather than your account:

• Is an agent CLI installed and logged in? Settings, Dex shows the fallback list that decides who answers you, and the status of each rung. If none is ready, install one from the Panel Library or complete its sign-in; the next section covers the usual failure modes.
• Voice is the one exception. Only voice needs a Deska account and remaining minutes, and it pauses when the month’s minutes run out. Check the balance on your account dashboard. See Plans & billing.

Claude Code, Codex and opencode are separate command-line tools that Deska drives; it does not bundle them. The easiest way to install one is the Panel Library (Cmd/CtrlShiftE): open the agent’s card, choose to install it, and Deska runs the install command for you in a terminal. Each tool manages its own sign-in.

When a configured agent refuses to start, it is almost always one of these:

• The binary is not on your PATH. By default Deska looks for claude, codex and opencode by name. If you installed one somewhere your login shell does not export, the instance shows Not installed and starting a session fails to spawn.
• A provider instance is overriding it. Each instance under Settings, Coding agents, Instances can pin its own binary path and home directory. A path that was right on your old machine, or a home directory that belongs to a different account, produces exactly the same failure as a missing binary. Clear the override to fall back to the default lookup.
• The CLI is signed out. Deska probes each instance for credentials and reports the result on its row. A probe that comes back unauthenticated means the tool itself needs a login, not Deska. Run the CLI once in a terminal panel and complete its sign-in.
• The CLI is too old. Each driver has a minimum version. Turn on CLI update checks and the instance row shows the exact update command for how that binary was installed, with a button to run it in a terminal.

Coding agents covers instances, runtime modes and what each driver expects.

A session with no active turn and nothing waiting on you is shut down after 30 minutes of inactivity. This is deliberate: idle CLIs would otherwise hold processes, ports and memory for the life of the app. The thread is not lost. It reads as stopped rather than failed, and the next message you send resumes the conversation from where it left off.

An error badge is a different thing. Those carry a reason (the process could not be launched, credentials were refused, the CLI is below the minimum version, the transport closed, or the provider never answered) and need one of the fixes above. See Agent threads.

When a thread gets its own git worktree, Deska runs the first script marked runOnWorktreeCreate in your project’s deska.json once in the fresh checkout, so the agent never starts in a half-installed tree. That hook is best-effort by design.

• No manifest, no problem. A project without a deska.json simply runs nothing.
• A malformed manifest degrades to a warning. Unknown keys are ignored and bad entries are skipped, each with a warning that shows up as thread activity. A hand-written config can never block thread creation.
• Long scripts are capped at 10 minutes. Dependency installs take minutes, so the cap is generous, but a hung script is killed rather than holding the thread’s first turn forever. The tail of its combined output is kept so you can see why.
• A failure is a warning, not a blocked thread. The thread still opens. Read the recorded output, fix the script, and delete and recreate the thread to run it again.

If pressing the voice shortcut does nothing, or nothing comes back, check:

• Microphone permission. Deska needs access to your microphone. Grant it in your operating system’s privacy settings, then try again.
• The right shortcut. Dictation is CmdShiftV on macOS and CtrlAltV on Windows and Linux. It is global, so it works even when Deska is in the background.
• Minutes and sign-in. Managed voice needs an account and spends minutes; if either is missing, dictation pauses. See Voice.

Yes, that is what remote access is for. For your own machines there is nothing to pair: turn on Settings, Remote Access on the desktop, sign in on the phone with the same Deska account, and this computer shows up in its list. From there you can attach to terminals that are already running, follow coding-agent threads and answer their approvals, preview a dev server, and talk to Dex.

One-time codes exist for a different purpose. Share this computer mints a code that grants another account access to this machine, and you can revoke that access later from the same page. If your phone is not listing a computer, check that the desktop is awake, signed into the same account, and has the Remote Access switch on.

The free plan connects from one client device at a time, so signing in on a new phone or browser offers to sign the previous one out; accepting is one tap and the old device simply asks you to sign in again. The computer limit is separate: it counts the machines you have linked, and the free plan allows three computer changes per period. When a change is refused, the message shows the date the allowance resets.

Paid plans lift the computer limit. See Plans & billing.

Signing in opens your browser, and the browser hands the result back to the desktop app through a deska:// link. That handoff depends on your operating system knowing which app owns the scheme, which can break after moving Deska between folders, running two installs side by side, or using an unpackaged development build. If the browser says you are signed in but the app still shows Not signed in, quit Deska completely, reopen it from its installed location, and start the sign-in again from Settings, Account. On Windows and Linux the link arrives as a second launch of the app, so a Deska that is blocked from launching again will silently swallow it.

Deska checks for new releases on its own, but never downloads one behind your back. The flow is:

1. A background check finds a release and an update card appears.
2. You click Download. The download runs with a visible progress indicator.
3. You click Restart now to install it immediately. If you would rather not stop working, do nothing: a finished download installs the next time you quit Deska.

The same states live in Settings, Updates, where the button reads Check for updates, Download v…, a progress label, then Restart to update. That page also holds the release notes and the Release channel switch. You can force a check any time from Help, Check for Updates….

Channels, release notes and the rest are covered in Updates.

• The download stalls or restarts. Sleeping the machine or losing the network can kill a download silently, so Deska watches for progress and restarts the download itself, up to a few attempts. If it gives up, the card turns into a manual download link.
• The restart does nothing. If the installer handoff does not take within about 30 seconds, Deska stops waiting and offers the manual download instead of leaving you with a dead button. Grab the installer from the link and install over the top; your settings and workspaces are untouched.
• The update is offered but the file is missing. Releases publish per operating system independently, so a version can be downloadable on macOS while the Windows build is still uploading. Deska tells you the build for your platform is on the way rather than offering a link that would fail. Check again shortly.
• macOS refuses to open a manually downloaded build. If macOS reports the app as damaged or from an unidentified developer, the download carries a quarantine flag. Clear it with xattr -cr /Applications/Deska.app and open the app again.
• Windows warns about the installer. Installers have been signed since 0.13.0, so a SmartScreen warning means you are running an older download. Fetch the current one from the download page.

• Shortcuts: reset individual chords or all of them in Settings, Keybindings.
• All settings: Settings, Diagnostics, Reset holds Reset all settings, which returns every preference to its default. It does not touch your project files.
• Lost the onboarding tour? Replay it from Settings, Getting started, Show onboarding tour.

Use Help, Report Issue… in the app, or email [email protected] and we will help. Paste the output of Copy diagnostics into your message and we can usually answer on the first reply.