# Install The Linux Beta The Linux beta targets x86_64 and ARM64 (aarch64) Linux: i3/X11 and compatible wlroots-based Wayland compositors such as Hyprland or Sway. Audio uses ALSA, including PipeWire systems with ALSA compatibility. Inference uses Vulkan when available and can fall back to the CPU. A GPU that hangs or fails while transcribing is remembered for its current driver, and Auto transcribes on the CPU on it until the driver changes. An integrated GPU slow enough to miss streaming deadlines is timed against the CPU once, and Auto keeps whichever is faster. General › Advanced › **Speech engine** picks Auto, GPU, or CPU (`hex settings set transcription_device cpu`). The window still needs a Vulkan driver, even with CPU inference; `vulkan-icd-loader` alone is not a driver. Install a driver for your GPU or a software Vulkan driver. See the Wayland requirements below. x86_64 machines need a 2013 or newer processor with AVX2 (Intel Haswell / AMD Excavator or later); on an older processor Hex shows a message and quits instead of starting. Linux opens the same window as macOS and Windows: Settings, Modes, and History. Meetings are macOS-only. Paste on Wayland uses `wtype` where the compositor offers the virtual keyboard protocol (wlroots compositors, niri) and the desktop's RemoteDesktop portal elsewhere (KDE, GNOME). Shortcuts are general: the desktop's GlobalShortcuts portal when it has one, otherwise your desktop's own keybindings running `hex` commands (see [Shortcuts](#shortcuts)). With **Labs › Live typing** on (`labs.live_typing`, off by default), a hotkey dictation's provisional words are an underlined input-method preedit in the focused text field and the final text is committed through `zwp_input_method_v2`, so it lands without the clipboard and Ctrl-V. `zwp_input_method_manager_v2` is a wlroots-family protocol (Sway, Hyprland, and other wlroots compositors); KWin and Mutter do not offer it, so KDE and GNOME use the paste above. Hex takes the input method when the capture becomes intentional (the hold threshold, or at once in Toggle) and gives the seat back at Finish or Cancel, including post-release processing; short taps and chords create none. It falls back to the paste above when the compositor does not offer the protocol, another input method (fcitx, ibus) holds the seat, the focused field has no active text input, the final text is multi-line, or the compositor does not answer in time. A CPU engine or a model that cannot stream shows no provisional words while speaking, but the final text still goes in through the input method. Hex checks the compositor's registry when the window loads: on a Wayland desktop without the protocol (GNOME) Settings › Labs keeps its card, disabled while off, with a note that this desktop offers no input method Live typing needs, and `hex labs` prints the same note in its list and after `hex labs on live-typing`. The toggle is not refused, and dictations paste normally. It has **not** been verified on a real compositor yet; only its unit tests and the build ran. With **Labs › Transform typed text** on (`labs.typed_text`, off by default), Settings › Output adds a **Typed text** section whose shortcut (`typed_text_hotkey`) is unbound until you record one. Pressing it while nothing records clears the clipboard, sends Ctrl+A and Ctrl+C to the focused field, runs the focused app's Output steps on the copied text, clears and copies again to check the field still holds that text, then sends Ctrl+V to replace it. Spoken formatting, spoken symbols, and filler words are dictation-only and do not run on typed text. It takes the clipboard for the job, including any paste still waiting to restore, and puts the saved clipboard back 500 ms after the paste unless something newer replaced it. If Hex could not snapshot the clipboard, the result stays on it. Without data-control on GNOME, text is read through `wl-paste`, the clipboard is cleared through `wl-copy --clear`, and a result Hex could not snapshot stays on the clipboard. Because it sends Ctrl+A and Ctrl+C, it is not meant for terminals. With **Terminal paste** on, it refuses before sending any key: its Ctrl+V would become Ctrl+Shift+V. Select-all replaces the whole field, so mixed formatting is not preserved, and on GNOME `wl-paste` may briefly take focus. With the lab off, Output and the listener are unchanged and the shortcut is not registered; `hex typed-text` runs the same job from a desktop keybinding, and refuses clearly when the lab is off, Terminal paste shortcut is on, or Hex isn't listening. For Nix/NixOS, use the [Nix guide](nix.md). Nix owns updates to that installation; Hex's signed updater owns only the direct-install layout below. ## One Hex Process Hex on Linux is **one process per user** (and per data directory), not a system-wide/root daemon. It owns the microphone, shortcuts, model downloads and workers, sounds, paste, History, the recording pill, and the window. The window is optional: closing it stops neither dictation nor a model download, and launching Hex again opens it. When the desktop has a tray (a StatusNotifierItem host, such as Waybar, KDE, or Omarchy's bar), Hex shows a tray icon: click it to open the window, or use its menu: **Show Hex**, **Paste last dictation**, the downloaded speech models, the update once one is ready (**Restart to update**), **Enable / Disable Hex**, and **Quit Hex**; while Hex records or transcribes, the menu and tooltip say so. Hosts that draw theme icons, such as Plasma 6, GNOME's AppIndicator extension, and Waybar, draw a symbolic mark in the panel's own text color, so it stays visible on a light or dark panel. Plasma 6 recolors it only with icon themes that follow the color scheme (Breeze and Papirus do); other themes show the mark's default color. Plasma 5 also prefers the icon name but has no panel palette, so its color there is untested. Hosts that don't use theme names get Hex's pixmap: white, and black when the desktop's color scheme prefers light (Waybar also falls back to it when it can't find the name). Hex reads that setting when it creates the tray, so a later switch applies at the next launch, and asks a running Plasma session to reload icons after writing the mark. Without a tray, quit with **Quit Hex** at the bottom of the window's sidebar, the launcher's **Quit Hex** action, or `hex quit`. The window opens at 980×760 logical pixels and floats on tiling window managers with no window rule: it maps with its minimum size equal to its maximum, which sway, Hyprland, niri, and X11 managers such as i3 float, then drops the maximum so you can resize it down to 860×560 or up to any size. macOS and Windows open the same resizable window. Settings live in `settings.json` in Hex's data directory, the same file macOS and Windows use. ```sh hex # open the window, starting Hex if needed hex start # start Hex in the background; no window hex status [--json] # query the running Hex, not an old log entry hex quit [--force] # finish accepted work, release the microphone, exit hex restart [--force] # restart the systemd unit in this desktop's environment # (over SSH: the one it last ran in) hex settings set sound_effects off # every control command (docs/cli.md) journalctl --user -u hex.service # diagnostics of the supervised process ``` `hex app` is the same as `hex`, `hex start` runs `hex app --hidden` in the background and waits until Hex answers, and `hex stop` is the same as `hex quit`; older desktop and autostart entries keep working after an update replaces only the executable. `hex quit` and `hex restart` refuse while a dictation records or transcribes unless `--force`. Linux runs the same control commands as macOS ([docs/cli.md](cli.md)): `settings`, `model`, `window`, `vocabulary`, `history clear`, `check-for-updates`, `onboarding reset`, `annotate status`, `launch-at-login` (the XDG autostart entry), `logs`, `commands init|check`, `history`, `meetings`, and `mcp`. A launch first asks the running Hex over its socket. If one answers, it forwards `Activate` with the launcher's `XDG_ACTIVATION_TOKEN` or `DESKTOP_STARTUP_ID` and exits 0; the running process opens or focuses its window. If none runs and the installer's (or Home Manager's) `hex.service` user unit is loaded, the launch writes an owner-only `session.env` and starts the unit, which reports readiness to systemd (`Type=notify`) once its socket answers, then forwards `Activate`. Otherwise (a custom data directory, `cargo run`, a desktop without systemd) the launching process becomes Hex itself. Two racing launches produce one Hex; the loser forwards and exits 0. `session.env` holds the display and session variables, the cursor theme and input method (`XCURSOR_THEME`, `XCURSOR_SIZE`, `XMODIFIERS`, `GTK_IM_MODULE`, `QT_IM_MODULE`), and, when set, `XDG_DATA_DIRS` and the locale (`LANG`, `LANGUAGE`, `LC_ALL`, `LC_CTYPE`, `LC_MESSAGES`). Missing display variables explicitly clear stale Wayland/X11 values inherited by the user manager; missing locale and data-directory variables are left to the user manager. A saved `XAUTHORITY` whose file is gone (Xwayland writes a new cookie at each login, so a reboot strands the old path) is replaced at startup by the user manager's current value, or dropped so Xlib uses `~/.Xauthority`. A unit started with no display at all (the desktop never imported its environment into systemd) adopts the user manager's `WAYLAND_DISPLAY`, else the newest Wayland socket of yours in `XDG_RUNTIME_DIR` that answers. One started with only Xwayland's `DISPLAY` does the same when `XDG_SESSION_TYPE` is `wayland` (from Hex's environment, else the user manager's): it takes the manager's live `WAYLAND_DISPLAY`, else the newest answering socket. Any other explicit session type (`x11`, `tty` from startx, `mir`, …) keeps its X display even when the user manager still names a nested compositor or another login's display, so paste keeps reaching X11 apps; only an absent type adopts a live manager display. Launchers (`hex`, `hex start`, `hex restart`) make the same decision before they write `session.env`, so the service and the launcher agree on the session; a launcher never adopts without a display, and when it would start the unit with nothing to write it still refuses with "Start Hex from your graphical login session". Without the adoption, a Wayland desktop's paste goes through XWayland, which native Wayland windows never see, and restoring the clipboard clears the compositor's. Hyprland imports nothing by default; add this to its config so the service, its paste helpers, and the HUD get your session: ```ini exec-once = dbus-update-activation-environment --systemd WAYLAND_DISPLAY XDG_CURRENT_DESKTOP ``` When the HUD can't show, Hex's log says why: no display, no layer-shell (and no XWayland), or the overlay failing to open, with its error. No permissions are granted. The unit is `PartOf=graphical-session.target`; desktops managing a custom session target must bind its lifetime to their login/logout lifecycle. Systemd restarts a crashed Hex (`Restart=on-failure`) without a window; after **Update**, the restarted Hex reopens the window. There is one Hex per user: a launch from another desktop session restarts the supervised unit in the new session, and refuses to take over an unsupervised one (quit it first). The socket is owner-only in Hex's data directory, with same-user peer credentials, versioned bounded frames, bounded queues, and I/O deadlines. It is not a network API or the macOS embedded transcription SDK service. It carries `Activate`, `Status`, and Annotate's recording commands. The `hex` control commands reach Hex through its local API's `POST /control`; dictation commands go straight from there to the listener, never through the window. The local API's `/dictations` (the TypeScript SDK's `hex.dictation`) also records on the listener while Hex is listening, as on macOS: one capture at a time, so a client's dictation and the shortcut never end each other. For development, run `cargo run --release`. `hex dictate` remains an explicit foreground diagnostic listener without the window or HUD and cannot coexist with Hex's listener. Like `hex service`, it adopts the session's Wayland display when its shell has none, or only Xwayland's `DISPLAY` on a Wayland login (#756, #1506). `hex` commands reach only the service listener, so a foreground `hex dictate` receives none and says so at startup when no shortcut is bound. With `HEX_APPLICATION_SUPPORT_DIR` set, launches never start, stop, or restart the installed user unit; they forward to the Hex using that data directory or become it. `HEX_SYSTEMD_UNIT` names another unit for isolated tests. `hex logs -n 40` is the diagnostic-log view (`hex status --lines` is gone). The window runs on Rune's app lifetime (`rune::App`): Hex starts it without a window, each `Activate` opens or focuses it with the forwarded token (on Wayland through `xdg_activation_v1`; without a token most compositors only mark it urgent), and closing it keeps the window's state for the next open. ## Install A Published Build Published builds exist for x86_64 and ARM64, as a bare executable, a `.deb`, and an `.rpm`. They are built on Debian 12 and need glibc 2.36 or later: Debian 12, Ubuntu 23.04, Fedora 37, current Arch, or newer. ARM64 builds use Vulkan like x64 and fall back to the CPU. ### Install script The script installs the bare executable for your architecture into a user-local layout (`~/.local/share/hex`) that updates itself. It installs the stable release, or the newest dev build (on the Dev update channel) while there is no stable release yet; set `HEX_INSTALL_CHANNEL=stable` or `=dev` to choose: ```sh curl -fsSL https://anoma.ly/hex/files/install-linux.sh | sh ``` If a runtime library is missing, the installer names the packages to install (with Arch names). Then open Hex from your application launcher, or run `~/.local/bin/hex`; its first run downloads a speech model. To install the dependencies up front, or to inspect the installer before running it: ```sh sudo pacman -S --needed alsa-lib curl jq \ libxkbcommon libxkbcommon-x11 libx11 libxcb openblas openssl util-linux \ vulkan-icd-loader wl-clipboard wtype xxd curl --proto '=https' --tlsv1.2 -fsSLO \ https://anoma.ly/hex/files/install-linux.sh less install-linux.sh sh install-linux.sh ~/.local/bin/hex model install ~/.local/bin/hex ``` When `wl-copy` is missing, the installer prints the commands to install the Wayland helpers: on Debian or Ubuntu, `sudo apt install wl-clipboard wtype`; on Fedora, `sudo dnf install wl-clipboard wtype`; on Arch, `sudo pacman -S --needed wl-clipboard wtype`. `wtype` is only needed on wlroots compositors and niri, where Hex uses it; GNOME and KDE paste through their RemoteDesktop portal. The installer verifies the signed release feed, exact artifact size, and SHA-256 before installing. It uses no root access. It creates the managed version layout, `~/.local/bin/hex`, a desktop launcher, and an XDG autostart entry and a `hex.service` user unit. It does not start recording during installation. General › **Launch at login** turns that autostart entry on or off (`~/.config/autostart/anomaly.hex.desktop`); Hex leaves an entry it did not write alone. Where the desktop has the Background portal (GNOME, KDE), Hex asks it at startup to run in the background, and Launch at login goes through it: the portal writes and removes that same autostart entry (marked `X-XDP-Autostart=anomaly.hex`). Elsewhere Hex writes the entry itself. The launcher entry below is written only when no installed package or data directory provides one, and left as it is while the program it starts is there. Installed by a version manager (mise, asdf), both entries start its shim (`~/.local/share/mise/shims/hex`), which outlives each version, so an upgrade can't strand them. An entry Hex wrote whose program is gone points at this Hex the next time it starts, or goes once a package ships its own. The launcher entry is `~/.local/share/applications/anomaly.hex.desktop`, named for Hex's app id `anomaly.hex`, which its windows also report. Earlier installs named both entries `hex.desktop`; Hex and the installer rename Hex's own. Its icon is `anomaly.hex`: packages install it in the hicolor theme, and a direct install gets it in `~/.local/share/icons/hicolor` when Hex first starts. The tray's symbolic mark, `anomaly.hex-symbolic.svg`, is always written there too, in `hicolor/scalable/apps`, because packages don't ship it. Remove the application while preserving logs and settings with: ```sh curl -fsSL https://anoma.ly/hex/files/install-linux.sh | sh -s -- uninstall ``` or, with a saved copy of the installer, `sh install-linux.sh uninstall`. ### Upgrading from 2.3.1 HEX 2.3.1 read every `/dev/input` device on Wayland, so it needed the `input` group. Current builds don't: they use the GlobalShortcuts portal or `hex` commands bound in your desktop (see [Shortcuts](#shortcuts)). Don't grant input access; install the new build instead. The new build is a separate install in `~/.local/share/hex` and imports nothing from 2.3.1's `~/.local/share/voice-control`, so set up the model and settings again. The installer refuses to replace 2.3.1's files, so remove them first (the paths below assume the default XDG directories): ```sh systemctl --user disable --now hex.service rm -f ~/.config/systemd/user/hex.service ~/.local/bin/hex \ ~/.local/share/applications/hex.desktop ~/.config/autostart/HEX.desktop systemctl --user daemon-reload rm -rf ~/.local/share/voice-control # optional: 2.3.1's settings, logs, and models curl -fsSL https://anoma.ly/hex/files/install-linux.sh | sh ~/.local/bin/hex model install ~/.local/bin/hex ``` On Hyprland, bind the shortcut in your config as described in [Shortcuts](#shortcuts). ### Debian, Ubuntu, Fedora, and openSUSE The `hex` package installs `/usr/bin/hex`, the desktop entry, and the systemd user unit `hex.service` (the same files as the AUR package below). Download it for your architecture from (`linux-arm64-deb`, `linux-x64-rpm`, `linux-arm64-rpm`), then: ```sh sudo apt install ./hex.deb # Debian, Ubuntu sudo dnf install ./hex.rpm # Fedora (zypper install on openSUSE) systemctl --user enable hex.service # optional: start Hex at login ``` There is no apt or dnf repository yet. Hex never replaces a package-installed executable: when a new stable release is out, Settings shows the command that downloads and installs its package. Package installs follow the stable channel, so a package from the dev channel learns of the next stable release only. ### AUR From the next release on, the AUR package `hex-bin` installs `/usr/bin/hex`, the desktop entry, and the systemd user unit `hex.service`, from the same release executable, for `x86_64` and `aarch64`. It is not on the AUR yet. With an AUR helper: ```sh yay -S hex-bin systemctl --user enable hex.service # optional: start Hex at login ``` pacman updates it; Hex never replaces a package-installed executable, and Settings says "Updated by your package manager". It is unrelated to the official `hex` package (a hex dump tool that installs `/usr/bin/hx`). ## Install From Source Install the native dependencies and, for a source build, the Rust toolchain: ```sh sudo pacman -S --needed base-devel git rustup python alsa-lib curl jq openssl xxd \ util-linux libxkbcommon libxkbcommon-x11 libx11 libxcb openblas \ vulkan-headers vulkan-icd-loader \ shaderc spirv-headers clang cmake pkgconf wl-clipboard wtype rustup default stable ``` Build and install Hex as your desktop user: ```sh git clone https://github.com/anomalyco/hex.git cd hex ./scripts/install-linux.sh ~/.local/bin/hex model install ~/.local/bin/hex ``` Do not run the installer as root. It installs a user-local binary, desktop launcher, and autostart entry in the same layout as published builds, and marks the version as a source build (`source-build` beside the executable). The in-app updater never replaces a source build; Settings shows "Updated from your source checkout", and you update by pulling and running the installer again. Installing a published release over it switches back to signed updates. With a custom `HEX_APPLICATION_SUPPORT_DIR`, `cargo run --release` runs an unmanaged development Hex instead; without one it forwards to the installed Hex. ## Dictate Hold **Alt-Space**, speak, then release. Double-tap the shortcut to keep recording, and press the same chord again to finish. **Shortcut mode** picks how the shortcut triggers: **Hold or double-tap** (the default), **Hold**, **Tap** (starts and stops with single presses), or **Double-tap** (waits for two complete taps, and needs a shortcut with a key). **Ctrl-Alt-V** pastes the last dictation again. Settings shows listener state, Start/Stop, and operational errors. Changing a shortcut or a setting the listener reads at start temporarily stops listening and restores the previous running state after the edit. Modes apply corrections, OpenCode rewriting, and transformations per application or website; the application picker lists `.desktop` entries. On X11, Hex reads the focused application from the active window's process name (`code`, `chrome`). On Wayland, compositors with the foreign-toplevel protocol (wlroots compositors such as Sway, niri, Hyprland) report the activated window's app ID, which Hex names by its `.desktop` entry (`google-chrome-stable`, `firefox`). GNOME and KDE don't report it, so the Global mode applies there. Website rules read the focused page's address through AT-SPI, the desktop accessibility bus, on X11 and Wayland. Firefox exposes it whenever the accessibility bus is running. Chrome and other Chromium browsers expose it only with accessibility turned on: launch them with `--force-renderer-accessibility` (for example in `~/.config/chrome-flags.conf`), or run a screen reader. Without it, the application rule applies. Completed dictations are kept in History. **Turn off the mic when not dictating** (General) releases the microphone between dictations; it then opens on the shortcut press without pre-roll. **While dictating** can mute the default output through `wpctl` (PipeWire) or `pactl` (PulseAudio), or pause playing MPRIS media players over D-Bus, once the hold passes 300 ms, so shortcut chords and short taps never do; Hex restores only what it changed. Cancelling shortcut capture preserves the old binding unless the new binding has already been saved; listening resumes only if it was previously running. ### Bluetooth headsets A Bluetooth headset can't play high-quality audio (A2DP) and use its microphone at once. While any application records from the headset's microphone, PipeWire (WirePlumber) or the headset switches it to the hands-free profile (HFP/HSP): mono, call-quality sound in both directions. This is how Bluetooth audio works, not something Hex chooses, and how quickly the headset switches back depends on the headset and WirePlumber's settings. If Hex records from the headset's microphone, **Turn off the mic when not dictating** trades off differently on and off: - **On** opens the microphone only when you press the shortcut, so each dictation switches the headset to hands-free and back. Playback drops out or pauses during the switch, and the microphone takes longer to open, so the first words can be lost. - **Off** (the default) keeps the microphone open, so the headset stays in hands-free mode, with call-quality playback, for as long as Hex listens. The recommended setup is a separate microphone for input (the laptop's built-in microphone or a USB microphone) and the Bluetooth earbuds for output only. Pick that microphone in General's **Microphone** list, or make it the system's default input (for example with `wpctl set-default`), so nothing opens the headset's microphone. General › Advanced's Bluetooth option (`avoid_bluetooth_microphone`, on by default) helps only part of the way: - It applies only while the microphone is **System default** and the default input is a Bluetooth headset. A Bluetooth microphone you picked in Settings, or `--device`, is always used as named. - It needs another hardware input that isn't reported unplugged, and `pactl` (PipeWire's PulseAudio server or PulseAudio) to move the stream. With no other input, Hex records from the headset. - On Linux, Hex can only open ALSA's default device, which is the Bluetooth source, and then moves its own stream to the other microphone. The stream is briefly on the headset first, so the headset may still switch to hands-free mode, and Hex doesn't switch its profile back. Forcing the headset's profile is up to your sound settings. - It changes only Hex's own recording, never other applications or the system default. To avoid the switch entirely, use the recommended setup above. ## Shortcuts Hex gets its shortcuts one of three ways, and all of them drive the same dictation rules: - **X11:** Hex grabs the shortcuts Settings records. - **Wayland with the GlobalShortcuts portal** (for example niri with `xdg-desktop-portal-gnome`, GNOME, or KDE): Hex asks the desktop for the shortcuts Settings records. The desktop decides: it may grant them, assign another key, or refuse one that it or another binding already uses. Settings lists what the desktop granted under **Desktop shortcuts**, with an error for any it refused. A desktop may keep an older binding when you record a new shortcut (KDE does); where its portal supports it, **Desktop shortcuts > Open** shows the desktop's own dialog for Hex's shortcuts, and Settings follows what you choose there. KDE asks once in a "Global Shortcuts Requested" dialog; Hex waits for your answer, and if you cancel it KDE asks again the next time Hex binds. Hex's shortcuts are listed under **Hex** in System Settings › Keyboard › Shortcuts. The portal identifies Hex by its app id `anomaly.hex`, its installed `anomaly.hex.desktop` entry, and by inspecting the Hex process. A downloaded executable has no entry, so Hex writes a minimal `~/.local/share/applications/anomaly.hex.desktop` that runs it (a managed install replaces it); if the portal still can't find it, restart the portal with `systemctl --user restart xdg-desktop-portal`. Run `hex service` directly: a setgid wrapper such as `newgrp`, once used to grant input-device access, makes the portal refuse Hex. The desktop delivers the keys to Hex, not to the focused application. On GNOME and KDE Plasma, new setups dictate with Ctrl+Alt+Space, because GNOME keeps Alt+Space for the window menu and Plasma for KRunner; Settings warns when a shortcut uses a key GNOME keeps for itself. Keys you change in GNOME Settings › Keyboard work at once, and Hex's Settings and `hex status --json` show them. Annotate's shortcut (F9 by default) sits under the dictation shortcut in General. **Disable** (General or the tray) keeps Hex disabled across restarts until you enable it again. On GNOME, Disable also removes Hex's entries from Settings › Keyboard › Global Shortcuts; Enable then asks you to approve them again. Hex also removes the duplicate list that versions before `anomaly.hex` left under the id `hex`. - **Hyprland** has the portal but takes every shortcut without a key, so nothing happens until you bind one in your config, and the key Settings records is not used. Hex can't tell whether your config binds it. Prefer keys without modifiers, because Hyprland adds every modifier you still hold to Hex's paste (see [Native Wayland Requirements](#native-wayland-requirements)). Avoid Alt in the bind too: Hyprland takes the key (Space) but lets Alt through to the focused window, so Electron apps with a hidden menu bar (Slack, Discord, VS Code) see Alt pressed and released alone, move focus to their menu, and the paste lands there instead of the message box (#1023). Hex still logs the paste as sent. Ctrl+Space or a key without modifiers works. Hyprland names each shortcut `anomaly.hex:`: `anomaly.hex:dictation`, `anomaly.hex:paste-last`, `anomaly.hex:capture` (Annotate), `anomaly.hex:raw-dictation` (Dictate without processing), and `anomaly.hex:terminal-paste` (Labs › Terminal paste shortcut, while on). The names stay the same when you record another key in Settings (#1376), so a bind keeps working; `hyprctl globalshortcuts` lists them while Hex runs. For example: ```lua hl.bind("End", hl.dsp.global("anomaly.hex:dictation")) hl.bind("F10", hl.dsp.global("anomaly.hex:paste-last")) ``` Traditional Hyprland configs write `bind = , End, global, anomaly.hex:dictation`. Hex 3.3 and earlier put the recorded key in the name (`anomaly.hex:dictation-ALT-space`); Hex still answers those names, but only for the key recorded in Settings when the bind was written, so switch them to the bare names before you record another key. Binds to `hex:dictation` or `hex:paste-last` (names from before Hex's app id was `anomaly.hex`) do nothing now, so replace them. Remove any `cancel-dictation` bind: Hex no longer has it. Hyprland 0.56's Lua binds send no release when the modifier comes up before the key (Alt before Z); 0.57 fixes this. On 0.56, Toggle is unaffected: the next press still finishes. In Hold, recording continues until the next press and release, so lift the key first or use Toggle. For hold-to-talk that doesn't depend on the portal's release, bind Hex's own commands instead (below), for example `bind = , End, exec, hex dictation start` with `bindr = , End, exec, hex dictation stop`, or one `bind = , End, exec, hex dictation toggle`. Pasting into a terminal needs **Terminal paste** (Ctrl+Shift+V) unless the terminal accepts Ctrl+V. - **Wayland without the portal** (for example Sway): nothing registers global shortcuts. Settings lists these commands; bind them in your desktop's own keyboard configuration. They reach only the listener `hex start` or `hex service` runs; a foreground `hex dictate` can't receive them: ```sh hex dictation start # bind to a key's press: start recording hex dictation stop # bind to the same key's release: stop and transcribe hex dictation toggle # one key: start, then stop and transcribe hex paste-last # paste the last dictation again hex typed-text # Labs › Transform typed text: replace the focused field's text hex dictation toggle --raw # dictate without processing: paste the words as heard ``` For example, hold-to-dictate on F9 in Sway, and a toggle in any desktop that runs commands on key presses only: ```sh bindsym F9 exec hex dictation start bindsym --release F9 exec hex dictation stop bindsym Ctrl+Alt+d exec hex dictation toggle ``` GNOME 46 and older (Ubuntu 24.04) have no shortcuts portal. There, Settings › Desktop shortcuts › **Add GNOME keyboard shortcuts** writes Hex's own entries into GNOME Settings › Keyboard › Custom Shortcuts with your shortcuts: `hex dictation toggle` (GNOME runs custom shortcuts on the key press only, so dictation toggles), `hex paste-last`, `hex typed-text` while Transform typed text is on and its shortcut is bound, and `hex annotate toggle` while Annotate is on. Hex removes them while it's disabled and puts them back when you enable it; **Remove** takes them out for good. Keys you change in GNOME Settings stay. Hex never touches your other custom shortcuts. `hex dictation stop --print` stops the same way, then waits up to 60 s and writes the transcript to stdout instead of pasting it, after the same processing a paste gets. Only that command waits; the listener stops recording at once, so a following `start` isn't blocked. No speech exits 4 and prints nothing; a failure, cancel, or timeout prints nothing, exits 1, and never pastes. History keeps the text as Printed, and Paste Last skips it. See `docs/cli.md`. The commands are safe to bind anywhere, including X11 beside the grabs. They talk to the running Hex and never start it: without one, or while Hex is not listening, they print a one-line error and exit non-zero. Starting while recording, and stopping while idle do nothing, so key repeat is harmless. Start and stop bypass Hold, Toggle, and double-tap: start records, stop finishes. A shortcut press also finishes a recording a command started. In **Tap** mode, a **Cancel** shortcut (Escape by default) throws away the recording: nothing is pasted or saved, and dictations already transcribing still finish. On X11, Hex grabs that key only while a recording runs, so it works normally everywhere else. On Wayland a desktop shortcut would hold the key all the time, so Hex binds nothing; bind `hex dictation cancel` to a key in your desktop's keyboard shortcuts instead. `hex dictation cancel` works in any mode. In the Hold modes there is no cancel: every dictation finishes and pastes. On KDE, Hex removes the Cancel dictation shortcut older builds asked for, so its key returns to your applications. Shortcuts need a non-modifier key. Modifier-only shortcuts, such as Super alone, are not supported on Linux. On X11, Hex grabs Escape only while Annotate draws, where it stops drawing. If another application holds it, drawing goes on and Hex logs it once. Recording sounds are enabled at 50% volume by default, including when upgrading older settings. A start sound is queued immediately when the shortcut starts capture, a stop sound marks the end of a retained recording (not completed transcription or paste), and a cancel sound acknowledges cancellation of an active capture. Brief taps still play the start sound, but recordings shorter than 300 ms remain discarded and do not play the stop sound. **Sound volume** in Settings is a slider from Off to 100%; releasing it saves without restarting the listener and previews the start sound unless it is at Off. `hex dictate` uses the same saved volume. Playback uses the default audio output through a bounded background worker; unavailable audio output does not prevent dictation. Closing the window leaves Hex running on both X11 and Wayland. The recording/processing pill never takes focus or intercepts clicks, with or without the window open: a Rune overlay that is a layer-shell surface on Wayland and an override-redirect window on X11. On a Wayland compositor without layer-shell (GNOME), only the pill opens on XWayland, as that X11 window with an empty input shape on the primary monitor; the rest of Hex, including the window and portal shortcuts, stays on Wayland. It needs the window's event loop, so it is unavailable when the window cannot start (no display or GPU) and in `hex dictate`. **Recording indicator** places it at the top or bottom of the screen, or turns it off. Insertion uses the clipboard and **Ctrl-V** for new installations. Enable **Terminal paste** in Settings for targets that require **Ctrl-Shift-V**. Labs › Terminal paste shortcut (`hex labs on terminal-paste-shortcut`, off by default) adds a second dictation shortcut whose paste is always Ctrl-Shift-V, while the main shortcut keeps this setting. On X11 Hex grabs it like the other dictation shortcuts; on Wayland it needs the desktop's shortcuts portal (Hex asks for `anomaly.hex:terminal-paste`). There is no `hex` command for it, so without X11 grabs or the portal the shortcut cannot be registered. Existing X11 settings retain their previous Ctrl-Shift-V behavior until changed. The target application must accept the selected binding. After a paste, Hex puts the previous clipboard back, as on macOS ([#391](https://github.com/anomalyco/hex/issues/391)). Before writing the transcript it reads every format the clipboard offers (text, rich text, images), up to 32 MiB within one second, and 500 ms after the paste shortcut serves them again from Hex until something else copies. It restores only if nothing newer replaced the transcript in the meantime: a later dictation, a copy, or another application. An empty clipboard stays empty. A larger or unreadable clipboard is left holding the transcript, and Hex's log says why. When automatic paste fails after `wl-copy` has taken the transcript, it stays on the clipboard for Ctrl+V. Nothing confirms the target read the paste, so a target stalled past the delay can paste the restored clipboard instead (see [#24](https://github.com/anomalyco/hex/issues/24)). Labs › Keep dictation on clipboard (`hex labs on keep-on-clipboard`, off by default) leaves each ordinary dictation on the clipboard instead: the paste snapshots nothing and schedules no restore, and a restore an earlier paste was still waiting to make is dropped, so a later paste with the lab off cannot bring an older clipboard back. A typed-text replacement, which saved the clipboard before it copied the selection, and a capture's PNG still restore, and while the lab is off nothing changes. On Wayland, restoring needs the compositor's `ext-data-control` protocol (KDE Plasma 6, recent wlroots compositors) or `wlr-data-control` (wlroots compositors, niri, Hyprland); without either the transcript stays, and Settings › Output says so. GNOME offers neither. There you can opt in to Labs › Restore clipboard on GNOME (`hex labs on gnome-clipboard-restore`, off by default): Hex then reads and restores the clipboard through XWayland, which GNOME keeps in sync with Wayland apps both ways. It works only while XWayland is already running (an X11 app is open and `DISPLAY` is set); Hex never starts XWayland, and otherwise the transcript stays and the log says why. The same rules apply: nothing newer is ever overwritten. On GNOME, Hex pastes through the RemoteDesktop portal, and GNOME shows its remote-control indicator while that session is open. Hex closes it 15 seconds after the last paste and reopens it at the next one with the grant you approved, so you're asked only once. ## Native Wayland Requirements - Export the compositor's nonempty `WAYLAND_DISPLAY` in the launch environment. Hex and its window (winit) select the same native backend even when XWayland's `DISPLAY` is also present. `XDG_SESSION_TYPE` alone does not select Wayland. - Install `wl-clipboard`. Every Wayland copy and paste runs `wl-copy`; without it, Settings and `hex status` warn while the listener runs, and a dictation fails naming the package to install. Hex copies each transcript, then sends Ctrl+V (or Ctrl+Shift+V with terminal paste) through one of two general paths, chosen at the first paste: - `wtype`, when the compositor offers the virtual keyboard protocol (`zwp_virtual_keyboard_manager_v1`; wlroots compositors and niri) and `wtype` is installed. - Otherwise the desktop's RemoteDesktop portal (`org.freedesktop.portal.RemoteDesktop`; KDE, GNOME). The first paste asks you to allow Hex to control the keyboard; Hex keeps the portal's restore token (`remote-desktop-token` in Hex's data folder), so it asks once. Revoke it in the desktop's settings. - With neither, the dictation fails with "Copied to the clipboard; press Ctrl+V to paste" and, with `wl-copy` installed, the transcript stays on the clipboard. There is no silent XWayland, direct-typing, uinput, or privileged input-injection fallback; the only XWayland uses besides the HUD are the opt-in clipboard restore above, the opt-in call recording controls below, and the opt-in Annotate overlays below. Transcript text travels on stdin, not command-line arguments. - The overlay uses layer-shell. Without it (GNOME), only the HUD opens on XWayland as an override-redirect, click-through window that never takes focus. The meeting capsules take clicks, so there a call offer opens the Meetings pane instead, unless you opt in to Labs › Call recording controls on GNOME (`hex labs on gnome-meeting-capsules`, off by default): the offer and recording capsule then float over the call on XWayland, taking clicks on their buttons but never keyboard focus. It works only while XWayland is already running; Hex never starts it. Annotate's capsule and ink take clicks too, so a capture records with no capsule unless you opt in to Labs › Annotate on GNOME (`hex labs on gnome-annotate`, off by default): the capsule and ink then float on XWayland the same way. Esc can't stop drawing there, so use the capsule's pen button or let go of a held Annotate key (a tap of it stops the recording). With neither, Settings reports that the HUD is unavailable rather than presenting a normal focus-taking window as an overlay. - Shortcuts come from the GlobalShortcuts portal or from your own keybindings for the `hex` commands ([Shortcuts](#shortcuts)). Hex reads no input devices and needs no `input` group membership or other device permission. If the desktop closes the portal session, the listener stops with an error and an active recording is cancelled; enable it again from Settings or `hex start`. - Hex can't see which keys are down on Wayland, and some compositors merge held physical modifiers into its paste: on Hyprland, Alt still held from Alt+Z turns `wtype`'s Ctrl+V into Ctrl+Alt+V, and a paste-last bound to Ctrl+Alt+V is matched by Hyprland again and never reaches the app. The RemoteDesktop portal shares the desktop's keyboard the same way. So when a shortcut with modifiers asks for a paste, Hex waits for its release (the portal's Deactivated) plus 250 ms, at most 2 s after a press whose release never comes. After a `hex` command, whose keybinding Hex can't see, it waits 250 ms. A modifier still held past that changes the paste, so bind keys without modifiers (End, F-keys) or let go of the modifiers before the transcript arrives. Hex logs a dictation as pasted once it sent the paste shortcut; it can't confirm the application accepted it. A compositor that passes a shortcut's Alt through to the app (Hyprland) can also open an Electron app's menu when Alt comes up, which takes the paste (see [Shortcuts](#shortcuts)). ## Updates And Validation Managed installs check for signed updates when Hex starts and every 24 hours until an update is ready. Hex downloads, verifies, and activates an available update, then offers an **Update** button in the window that restarts the unit and reopens the window. The next launch through `~/.local/bin/hex` also uses the activated version. The signed update path is implemented but still awaiting a complete cross-version validation on the supported Arch/i3 host. See [`plans/linux.md`](plans/linux.md) for the engineering contract and remaining validation work. The native Wayland implementation builds on the feature proposed in [PR #28](https://github.com/anomalyco/hex/pull/28), with separate input-state, lifecycle, and paste regression coverage. Physical device, compositor, and target-application smoke tests remain necessary before a release. `scripts/test-wayland-paste.sh /path/to/compiled-test-executable /path/to/hex` runs the real paste helpers against a GTK target under an isolated headless Sway compositor. Its first paste runs while another virtual keyboard holds Ctrl and Alt. It then checks that every format of the previous clipboard comes back after the paste, and that an empty clipboard stays empty. It also starts an isolated Hex, opens its window through a second `hex app` (the window must belong to the same process), repeats paste while the window is open, closes the window, checks that the same process still answers, opens the window again (`HEX_WAYLAND_REOPEN=0` skips that), and quits. It requires the GTK development libraries, Sway, `wl-clipboard`, `wtype`, `dbus-run-session`, and a Vulkan driver (Mesa's software driver is sufficient), and must run as a non-root user. It uses isolated app data and no microphone; CI runs it with the display-free suite and Xvfb hotkey tests. `scripts/test-linux-dictation.sh /path/to/hex /path/to/parakeet-unified-en-0.6b-Q8_0.gguf /path/to/jfk.wav` checks the complete X11 app dictation path with a private PulseAudio virtual microphone and Xvfb display. It opens the window in the running Hex through a second `hex app`, replays the public JFK sample from whisper.cpp, holds and releases the real shortcut, verifies the transcribed words in a GTK editor, and checks orderly application shutdown and microphone release. It needs PulseAudio, its ALSA plugin, `xdotool`, Xvfb, the GTK development libraries, and a Vulkan driver for the window (Mesa's software driver is sufficient). It runs as a normal user with temporary settings; it does not use physical audio devices or personal recordings. CI downloads and verifies the pinned model and sample for this check. `python3 scripts/test-linux-service.py /path/to/hex` is a display-free, device-free single-instance check: commands fail fast without Hex, `hex start` becomes Hex, second launches (`start`, `app --hidden`, `service`, `app`) forward and exit 0, a window request without a display fails only the window, same-user socket permissions, version-1 clients get an error, invalid, oversized, and stalled frames, crash/stale-socket recovery, two racing launches yield one Hex, `hex quit` drains and removes the socket, and a custom data directory never runs `systemctl`.