Troubleshooting & FAQ

Open your account page and check that you are signed in with the account used for the purchase. If the plan is still confirming, use Check again. Once confirmed, Open Deska opens Deska in the browser. A Pro plan opens your own linked computers; it does not create a Cloud computer.

If Cloud is active but its computer has not appeared, continue setup to check the included computer and retry if needed. If a computer is asleep or offline, use its wake or connection action. If no agent can run, open that computer’s agents and connect one. OpenCode’s free models, when available, let you try a task without signing in to another provider. GitHub is optional for that first task.

On a replacement iPhone, Restore purchases checks the App Store purchase. Use the Deska account that originally bought it. See After buying Pro or Cloud.

When something goes wrong, click the ? at the top right of the window and choose Report a problem. It is also under Help, Report a Problem in the menu bar, behind bug in the command palette, and in Settings, Help. Say what happened in a sentence if you can (it is optional) and press Send report. Deska attaches what it knows: the same facts as Diagnostics below, your plan, how many projects and panels are open, the last part of its log and a screenshot of the window as it looked when you opened the report.

Before anything leaves, the home folder in paths becomes ~, links keep only their site, and email addresses, keys and tokens are removed. You can switch off the log and the screenshot, and See exactly what is included shows the full text. Your email goes only if you turn on You can email me about it. Conversations, prompts, file contents and panel names are never included.

After sending you get a short code such as DSK-3F9A1C. Post it in the Deska Discord so we can match the report to you and answer there. Save to file writes the same report to a text file instead, for when you would rather attach it yourself. Where an organization keeps reports inside the company, saving is the only option.

For a question rather than a bug, the same ? opens Join our Discord, where the team and other people using Deska answer. You also find it under Help in the menu bar, by typing discord in the command palette, and in Settings, Help.

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), one row per coding agent with its version and whether it is signed in, 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, OpenCode, Cursor, Antigravity, Pi, Hermes, Mistral Vibe, and Kimi Code), so most checks are about the engine rather than your account. Dex does need you signed in to Deska, though: signed out, it asks you to sign in first, and the free plan allows five Dex turns a day. A turn that fails before Dex answers or does anything, for example because no agent is installed, does not count.

• Is an agent CLI installed and signed in? Settings, Agents shows which agent Dex answers with and the status of each one. If none is ready, use Install or Connect account on its card, then Check Dex to confirm it answers; the next sections cover the usual failure modes.
• Voice runs on Deska’s keys. It 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, OpenCode, Cursor, Antigravity, Pi, Hermes, Mistral Vibe, and Kimi Code are separate command-line tools that Deska drives; it does not bundle them. The easiest way to install one is Settings, Agents: choose Install on the agent’s card, and Deska installs it for you in the background, without a terminal. The Panel Library (Cmd/CtrlShiftE) offers the same Install on the card of an agent that says Not installed, or a link to its installation guide when the agent needs npm and this computer has none. Each tool manages its own sign-in, which Connect account runs on the agent’s card (or in its terminal, opened in front, for an agent that asks its own questions).

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, opencode, cursor-agent and agy 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 agent under Settings, Agents can pin its own binary path and home directory under Advanced. 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 card. Not signed in on this computer. means the tool itself needs a login, not Deska: choose Connect account and follow the steps on its card, which updates by itself when the sign-in lands. Not checked yet. (Account not checked in Tools & accounts) is different: Deska could not confirm the sign-in without running the agent. It may well be signed in. Run Check tasks or Check Dex on the card for a real answer; each check sends a short request using your provider account.
• A task fails with “OAuth session expired and could not be refreshed”. That is Claude Code saying its saved login is gone: the token it keeps can no longer be renewed, often because you signed out elsewhere or the login was removed from the keychain. The turn reads Signed out and Claude Code could not use the sign-in for [email protected]. Sign in again to keep going., with Claude Code’s own message folded underneath, and Settings says the sign-in for that account expired. Press Sign in again, in the task or on the agent’s card, finish the login, and send the message again. Other agents refusing their login read the same way under their own name.
• Sign in says Deska could not start the CLI. In Tools & accounts, a sign-in that fails before the tool even runs shows the reason in the tool’s own words and the login command, such as claude auth login. Click it to copy, run it in a terminal on that computer, and come back: the card updates on its own. Before version 1.25.0, Windows computers failed here with exit null.
• The CLI is too old. Each driver has a minimum version. With CLI update checks on (it is by default) the agent card shows the exact update command for how that binary was installed. Update runs it in the background and the card shows its progress, or copy it to run it yourself. A Claude Code installed with Anthropic’s own installer updates with claude update, never with npm.
• OpenCode 2 is installed. Since version 1.30.0 Deska runs OpenCode 1 and OpenCode 2 (the @opencode/cli npm package, which uses the same opencode command), and picks the right one from the installed version. On an older Deska a task on OpenCode 2 stops with is not supported in Deska yet: update Deska, or switch back with opencode service stop, then npm uninstall -g @opencode/cli, then npm i -g opencode-ai@latest --allow-scripts=opencode-ai. A separate OpenCode account still needs OpenCode 1.
• OpenCode reads Not installed right after installing it. Newer npm versions can skip the setup step OpenCode’s package runs, and leave a opencode command that cannot start (on Windows the card used to say spawn UNKNOWN). Install it again allowing that step: npm i -g opencode-ai@latest --allow-scripts=opencode-ai, or for OpenCode 2 npm i -g @opencode/cli@latest --allow-scripts=@opencode/cli, then press Check again on the agent’s card. The card says when this happened, and its Install button allows the step.

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

Install works on Windows too, in the background. Claude Code, Codex, OpenCode, Pi and Kimi Code install through npm. When Node.js is not on the computer, Deska asks Codex needs Node.js first and installs both: Node.js with its official Windows Installer from nodejs.org, then the agent. Windows asks for permission once; choose Yes. Install it myself opens nodejs.org instead. Antigravity and Cursor use their official PowerShell installers, and Mistral Vibe installs uv first when it is missing.

When an install fails, the card names the reason (no connection, the permission prompt was declined, another installer is running) and keeps the installer’s last line; Details shows its whole output. Try again runs it again, and Open in terminal runs the same command where you can watch it. If the agent still reads Not installed after it finished, open Advanced and set Binary path to the executable, for example codex.exe. Connect account then signs it in on its card.

Both mean a tool is missing on this computer: Git for Source Control, the GitHub CLI for GitHub. Deska now says which one and installs it: open Tools & accounts and press Set up on the GitHub row, or Install Git in Source Control. The steps check again on their own, with no restart. Read more.

If a newer model is missing, update the agent on the computer running the task, then choose Rediscover on its card. Updating Deska alone does not update that agent. Claude Code needs version 2.1.280 or later for Opus 5.5; older models can still appear as choices. An older model in the list does not mean it is the newest one available.

Deska reads each agent’s model list from the CLI and your account. When that read fails, the agent card shows Model discovery failed with the reason, and the task’s model menu shows Could not load models, keeping the last list it had when there is one.

• Press Rediscover (or Discover models) on the card, or Retry loading models in the menu.
• If it keeps failing, check that the agent is installed and signed in, then run Check tasks on its card.
• When the list loads but the recommended family is not in it, the card says, for example, that no Sonnet model is available for this connection. Deska does not start a different model in its place. Set Model selection to Specific model or Provider default.

A task or Dex turn that needs a model Deska cannot resolve stops with the same message rather than silently running on another one. See Default models.

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, the provider never answered, or the model stayed at capacity) and need one of the fixes on this page. See Agent threads.

Older Deska builds could lose Codex updates after you sent several large screenshots, while Codex kept working. Update Deska on the computer running the task. Each image can still be up to 10 MB; sending several images together does not reduce that limit.

If the connection closes, the task shows an error. Review the files already changed, then send a new message in the same thread to resume its saved conversation. Deska does not automatically repeat the interrupted request. A command refused by Codex or a model-list timeout is a separate notice; changing Full access does not repair a closed connection.

“Selected model is at capacity” comes from OpenAI: the model you picked has no room for more requests right now. It is not your plan’s limit, so it can happen with most of your usage left. Codex gives up on these requests at once.

Deska keeps the task running instead and asks again on the same model: after 15 seconds, then 30 seconds, 1, 2 and 4 minutes. The thread shows a Retrying line with the wait. The conversation already holds your request and every step taken, so the next try carries on where the refused one stopped. A message sent with Steer now during the wait goes out at once as the next try, a queued one waits for the turn to end, and Stop ends the task as usual.

If the model is still busy after five tries (about eight minutes), the turn fails and says so. Send a message later to carry on, or pick another model in the composer. Dex and automatic titles do not wait: they fail at once, and Dex asks the next agent.

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.
• The input device. A recording that comes back with no words is almost always the wrong microphone or one that is muted. Pick the right one from the microphone menu on Dex. The recording itself is kept in the voice history, so you can retry it there.

Yes, that is what remote access is for. For your own machines there is nothing to pair: turn on remote access in Settings, Phone, under Remote access on the desktop, sign in on the phone with the same Deska account, and this computer shows up in its list. On Deska Pro you can then attach to terminals that are already running, follow coding-agent threads and answer their approvals, preview a dev server, and talk to Dex. On the free plan the list shows your computers and can wake them, and opening one offers the upgrade.

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 keeps one client device signed in 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. On the free plan those devices list your computers and can wake them, but opening one is part of Deska Pro, and trying to explains that and offers the upgrade. 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.

When you use Deska at app.deska.dev on a phone and sign an agent or GitHub in on one of your computers, the sign-in page opens in another tab. Phone browsers pause the Deska tab while you are away, which drops its connection to the computer. Computers on older Deska versions stopped the sign-in at that moment, so the page could say you were all set while Deska never heard about it.

Now the computer keeps the sign-in going for ten minutes without a connection. Come back to the Deska tab after approving: it says it is reconnecting, then shows the account as signed in. If the browser reloaded the tab, the sign-in opens again where it was. Check now asks the computer right away. If it still says the sign-in stopped, update Deska on that computer and try again.

Deska checks for new releases on its own, but never downloads one behind your back, with one exception covered in Updates. 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 and Restarting…. 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. Restart now turns into Restarting… the moment you press it. If Deska is still open about 20 seconds later, the card says Deska didn’t close for the restart and offers Try again; quitting and reopening Deska also finishes the update. If Deska comes back on the old version, it picks the update up again without downloading it. See If a restart does not finish.
• 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 when opening Deska. SmartScreen may not yet recognize a new version. Extract the ZIP from the download page and follow the Windows guide if you see Windows protected your PC.

If Deska opens on a screen that says it could not open the window, the app saved something on your computer that this version cannot read. It usually happens right after an update. Nothing of yours is lost, and the screen is the way back.

Press Reload first. Most of these pass on their own, and Deska tries it for you: a window that fails twice in a row clears the data it can rebuild by itself on the next launch, which for now is the list of community panels it keeps so your panels draw instantly. It never clears your drafts, your layout, your shortcuts or your permission answers without you asking.

If it comes back, press Repair and reopen. That one sets aside everything this window saved on your computer, including your drafts and shortcuts, and keeps a copy of every one of them in a folder you can open from the same screen. Your projects, your files and your account are never touched: they do not live there.

Copy the details puts the version and the error on your clipboard. Paste it in the Deska Discord and we can tell you what happened.

• 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.
• Missed the onboarding tour? It plays on first launch, and the installed app has no replay button in Settings. The small one-time tips that open the first time you use a panel follow Tips on new surfaces under Settings, Help, Learn Deska.

Report bugs, share ideas or get help in the Deska Discord. You can also email [email protected] and we will help. Send a report from the app first and include its code, or paste the output of Copy diagnostics, and we can usually answer on the first reply.