Getting started

Install Voisu, add your Deepgram and Groq API keys, and make your first Recording. It takes a few minutes on either platform.

Before you start

Using Claude Code, Codex or another terminal agent? Install with an agent gives you a prompt to paste. The agent runs the steps below, and you type your keys into Voisu yourself.

Install

Pick your system. Each tab ends with Voisu running and your keys saved.

Windows

Windows 10 / 11 · x64 · installs for your user, no admin needed

  1. Download the installer.

    Download for Windows Voisu-Setup-x64.exe

  2. Run it. The installer isn't code-signed yet, so SmartScreen may warn on first run: choose More info → Run anyway. Voisu installs for your user account only.

  3. Add your keys. Voisu opens its setup screen on first launch. Choose Get a free API key on each card, paste your Groq and Deepgram keys, and choose Save and start. Voisu checks each key with its provider before saving it. Both keys are required. The step-by-step Windows guide walks through it with screenshots.

Voisu now lives in the tray and turns on Start at login after your first successful setup. You can close the settings window; it reopens from the tray's Settings… item.

macOS

Apple Silicon (M1 or newer) · macOS 13 Ventura or newer · lives in the menu bar

  1. Download the disk image, open it and drag Voisu onto Applications.

    Download for Mac Voisu-macOS-arm64.dmg

  2. Let macOS open it. Voisu isn't notarized yet, so the first open is blocked. Choose Done (not Move to Trash), then System Settings → Privacy & Security → Open Anyway.

  3. Allow the permissions: Microphone, Accessibility (so Voisu can paste) and Input Monitoring (for the Trigger Key). Quit and reopen Voisu once after granting them.

  4. Add your keys. Paste your Groq and Deepgram keys into the setup window and choose Save and start. They're stored in the macOS Keychain.

Then hold Control Option, speak and let go. The step-by-step Mac guide covers each screen.

Fedora

Fedora · KDE Plasma or GNOME on Wayland · COPR

  1. Install the package. The overlay is the optional on-screen capsule.

    $ sudo dnf copr enable anuraj-dev/voisu
    $ sudo dnf install voisu
    # optional on-screen overlay:
    $ sudo dnf install voisu-overlay
  2. Start the daemon for your user. Voisu runs as a systemd user service, so nothing needs root from here on.

    $ systemctl --user daemon-reload
    $ systemctl --user enable --now voisu.service

    If you installed the overlay, turn it on too:

    $ systemctl --user enable --now voisu-overlay.service
  3. Choose your Trigger Key. On KDE Plasma and GNOME, your desktop shows a dialog the first time the daemon starts. Pick the key there; the choice persists.

  4. Add your keys. Setup asks for both and checks them with each provider. Afterwards, run voisu any time to see whether Voisu is ready and to change settings.

    $ voisu setup

Arch

Arch Linux · AUR

  1. Install the package.

    $ yay -S voisu-bin

    To build from source instead, install voisu. The two packages conflict, so pick one.

  2. Run setup. It asks for your API keys and checks them with each provider. Afterwards, run voisu any time to see whether Voisu is ready and to change settings.

    $ voisu setup

    On Hyprland there is no shortcut dialog, so setup binds the Trigger Key for you: Caps Lock if you accept the default, or Right Alt if you decline or Caps Lock is already bound. It also starts Voisu's services. Using Caps Lock as the Trigger Key stops it toggling caps on that key.

Debian / Ubuntu

Ubuntu 26.04 LTS · GNOME Wayland · amd64

  1. Add the repository and install.

    # Add Voisu's signing key.
    $ sudo install -d -m 0755 /etc/apt/keyrings
    $ curl -fsSL https://anuraj-dev.github.io/voisu/voisu-archive-keyring.asc \
        | sudo tee /etc/apt/keyrings/voisu-archive-keyring.asc >/dev/null
    
    # Add the repository.
    $ echo 'deb [signed-by=/etc/apt/keyrings/voisu-archive-keyring.asc arch=amd64] https://anuraj-dev.github.io/voisu stable main' \
        | sudo tee /etc/apt/sources.list.d/voisu.list
    
    # Install.
    $ sudo apt-get update && sudo apt-get install -y voisu

    Signing key fingerprint
    4149 EE38 68B3 6B60 0759 2966 D08B CFDC 3412 5B28

    Verify the key first
    # Fetch the key to a temp file and check its fingerprint before trusting it.
    $ EXPECT=4149EE3868B36B6007592966D08BCFDC34125B28
    $ curl -fsSL https://anuraj-dev.github.io/voisu/voisu-archive-keyring.asc -o /tmp/voisu.asc
    $ gpg --show-keys --with-colons /tmp/voisu.asc \
        | awk -F: '$1=="fpr"{print $10; exit}'
    # The printed fingerprint must equal $EXPECT before you add the key above.
  2. Run setup.

    $ voisu setup

    Setup asks for your API keys, enables the daemon and the native GNOME capsule, and uses Ctrl Space as the Trigger Key by default. If it asks, log out and back in, or reboot.

Other desktops (X11, Cinnamon)

X11 sessions · no shortcut portal

Install with your distribution's tab, then bind the Trigger Key yourself. In System Settings → Keyboard → Shortcuts → Custom Shortcuts, add a shortcut that runs:

$ voisu toggle

On X11 Voisu uses xclip for the clipboard, and its feedback arrives as desktop notifications instead of the capsule.

Your first Recording

  1. Click into a text field: an editor, a chat box, a browser address bar.

  2. Windows: hold Ctrl Win and speak. Mac: hold Control Option and speak. Linux: press your Trigger Key once and speak. The capsule appears and shows your voice.

  3. Windows and Mac: release the keys. Linux: press the Trigger Key again.

  4. The capsule switches to Processing, then the Transcript lands at your cursor.

Nothing happened? On Linux, run voisu doctor. It checks the daemon, the shortcut portal, Delivery and your keys, and voisu doctor --verbose explains each result. On Windows, try Test paste (in 3 s) from the tray. Troubleshooting covers the common cases.

Next steps