Troubleshooting

Start with deskwink doctor

It checks the things that most often go wrong and tells you what to do about each one:

• your Node.js version (22 or newer is required);
• that DeskWink can reach the internet over a secure connection, and that your computer’s clock is close enough to the real time;
• that DeskWink’s stored key can be read;
• that the folders you shared still exist;
• on a Mac, the permission state for protected locations such as Desktop and Documents;
• that the background process is running.

Add --json for output a coding agent can read. Add --report to create a diagnostic bundle with personal details removed; it is the most useful thing to attach when you write to [email protected]. You can also look at the latest log lines with deskwink logs --lines 100. The log contains metadata only, never file contents or command text.

Installing

“deskwink” is not recognised, or “command not found”

Open a new terminal window so it picks up the changed PATH. If it still fails, find where npm puts global programs with npm config get prefix and make sure that folder (on Mac, its bin folder) is on your PATH.

PowerShell says “running scripts is disabled”

Windows PowerShell can block npm’s .ps1 wrapper files. You do not need to change any system setting. Use the .cmd versions instead:

Command Prompt (cmd.exe) does not have this restriction either.

On a Mac: EACCES permission denied

Do not use sudo. Give npm a folder in your home directory for global programs, add it to your PATH, and install again:

Then add ~/.npm-global/bin to the PATH in your shell profile and open a new terminal.

Node.js is missing or too old

Run node --version. If it is lower than 22, install the current LTS version from nodejs.org, or with winget install OpenJS.NodeJS.LTS on Windows or brew install node on a Mac.

Pairing

The pairing link or code does not work

Codes are valid for 5 minutes and work once. Run deskwink launch again to get a new link and code. Make sure you confirm the code that your terminal shows.

The browser did not open

Copy the link from the terminal into a browser yourself. Pairing has to be done by you in a browser where you are signed in to DeskWink.

Connection and state

Run deskwink status. The state tells you where to look.

My AI says the computer is offline

DeskWink only works while it is running. It does not start by itself after a restart, logout or sleep that stopped it, and it does not queue requests, so a request made while the computer was offline fails straight away and is not run later. Run deskwink launch and ask your AI again.

The state stays “connecting”

DeskWink connects out over a secure connection. Networks, proxies and security software that block long-lived secure connections (WebSockets) can stop it. Run deskwink doctor; if it reports a network, certificate or clock problem, fix that first.

The state is “suspended”

You, or someone with access to your account, used the emergency disconnect in the console. Resume your computers in the console, then run deskwink launch on the computer.

The state is “revoked”

This computer was removed from your account. Run deskwink logout to clean up, then deskwink launch to pair it again.

The CLI says its version is too old

Folders and files

My AI cannot see a folder or file

• Run deskwink folders list. If the folder is not listed, add it with deskwink folders add <path>.
• Check that you allowed this computer for that AI app on the DeskWink permissions page; you can look at and change it in the console.
• Some files are blocked even inside a shared folder: SSH and cloud credentials, .env files, private keys, password databases, browser profiles and the inside of .git folders. See the security model.
• Paths that lead outside a shared folder, for example through a shortcut or symbolic link, are refused.

My AI cannot change files

A folder added without --write is read-only. Remove it and add it again with --write, and check that the AI app was given the ability to propose changes.

A change is waiting and nothing happens

That is by design. Changes to files wait for your approval in the DeskWink console. Approve or reject them there; requests that nobody answers expire.

A command is waiting

Commands are approved on your computer, not in the web console. In a terminal on that computer, run deskwink approvals list, then deskwink approvals approve <id>.

I want a change undone

Use the execution id of the change: deskwink restore <execution-id>. Backups are kept for 7 days.

On a Mac, DeskWink asks for permission to a folder

macOS asks before programs read protected locations such as Desktop, Documents and Downloads. Allow it for the terminal or program that runs DeskWink. deskwink doctor shows what is allowed.

Still stuck?