Troubleshooting

Most problems are one of a handful of things: the paste couldn't land, the desktop hasn't granted a permission, or a key or microphone isn't set up. Start with the message the capsule showed you.

On Linux, open voisu or run voisu doctor first. It checks the daemon, the shortcut and RemoteDesktop portals, the clipboard and your keys, and tells you what to do about anything that fails. voisu doctor --verbose shows the reasoning behind each check.

The Trigger Key does nothing (Linux)

Voisu isn't running after login (Linux)

The daemon waits up to 20 seconds for your desktop session to come up. If voisu service status still shows it inactive or failed, start it once the desktop is ready and check its log:

$ voisu service restart
$ journalctl --user -u voisu.service

On Windows, turn on Start at login in the tray menu or settings window.

Wayland portal permissions (Linux)

On Wayland, Voisu asks the desktop for permission through portals instead of reading your keyboard directly. It never needs root or uinput access.

If you refused the Remote Desktop prompt, or want to be asked again, reset the grant Voisu saved:

$ rm ~/.local/state/voisu/remote-desktop.restore-token
$ systemctl --user restart voisu.service

This clears only Voisu's own saved grant. A permission your desktop remembers by itself isn't cleared by this.

On GNOME, a few voisu doctor results are expected: Paste action and Paste backend show SKIP (they're Hyprland checks), and Focus guard shows WARN because GNOME can't report the focused window. The capsule is the overlay@voisu.app Shell extension there, so an inactive voisu-overlay.service is normal.

Keys

Microphone (Windows)

The paste didn't land

Your words are kept either way. On Windows, copy them from the Last Transcript card on the Overview tab (Settings… in the tray). On Linux they're on your clipboard.

Windows messageWhat it means
Can't type into an admin windowSee Admin windows.
Click into another app firstThe Recording started while a Voisu window had focus. Click where you want the text, then dictate.
The window you were typing in closedThe window that had focus when you started is gone. Copy the Transcript from Last transcript.
Couldn't return to your windowWindows wouldn't bring the original window back to the front.
Another app replaced the clipboard; nothing pastedA clipboard manager or another app wrote to the clipboard mid-paste. Copy from Last transcript and try again.

Use Test paste (in 3 s) in the tray to check one app on its own: click into it within three seconds and watch whether the sample text appears.

Linux terminals. On GNOME, Voisu pastes by sending Ctrl V. A terminal that pastes with Ctrl Shift V receives nothing, but the Transcript is on the clipboard, so paste it yourself.

Linux, GNOME. GNOME doesn't let Voisu check which window has focus, so paste lands in whatever window has focus when you stop. To paste by hand instead, switch with voisu delivery copy.

Admin windows (Windows)

Windows doesn't let an ordinary app type into a window running as administrator, such as an elevated terminal, Task Manager or an installer. It drops the keystrokes silently, so Voisu checks first and shows Can't type into an admin window instead of pretending it worked.

Copy the Transcript from Last transcript and paste it yourself, or run the target app without elevation.

SmartScreen (Windows)

The installer isn't code-signed yet, so Microsoft Defender SmartScreen may show “Windows protected your PC” the first time you run it. Choose More info, then Run anyway. The installer comes from the project's GitHub releases, and updates after that are signature-checked before they install.

Reporting a bug

Open an issue on GitHub with your OS, desktop and what the capsule said. On Linux, voisu history lists recent Recordings with their IDs, and voisu export <id> writes a redacted export of one you can attach. On Windows, the log folder is shown at the bottom of the settings window.

Nothing is sent anywhere unless you attach it yourself.