Troubleshooting
Start with the environment, then read the log.
Most first-launch failures come from Node.js discovery, npm connectivity or operating-system trust prompts.
1. Verify Node.js and npx
node --version npx --version
Install Node.js 18 or later if either command fails. If Node was installed while the app was open, quit and restart the app so it can see the updated environment.
2. Allow the first download to finish
The first start downloads the pinned DSH package and can take longer than later launches. Check npm registry access, proxy settings and local firewall rules.
3. Read the desktop log
~/.dsh-desktop/logs/dsh.log
Include the relevant section when reporting a bug, but remove API keys, tokens, home-directory names or other sensitive information first.
4. macOS blocks the app
Right-click the app and choose Open. If you intentionally remove the quarantine attribute, first verify the download source.
xattr -d com.apple.quarantine "/Applications/dsh-desktop.app"
5. Windows shows SmartScreen
The v0.1.4 executable is unsigned. Use “More info” only if you downloaded it from this project's GitHub Releases page and accept that trust model.
6. Port 3080 is already used
No action is normally required. The app automatically tries another available local port.
7. Report a reproducible issue
Include the desktop version, operating system and architecture, Node.js version, exact steps, expected result, actual result and sanitized log output in a GitHub issue.