Install and launch
For OSS, the repository installer is the most complete route because it handles Linux system dependencies, an isolated Python environment, the Piper voice model, the launcher, desktop menu entry, and autostart.
git clone https://github.com/avrvx/AverVOX-OSS.git
cd AverVOX-OSS
bash install.sh
avrvxPro is delivered after purchase through the licensed download path. Make the downloaded AppImage executable, run its installer mode if directed by the release instructions, and enter the license key when prompted. The Pro runtime is bundled, but supported desktop and audio dependencies still apply.
Use OSS to verify audio, hotkeys, text insertion, target applications, and the real LLM endpoint before purchasing Pro.
Desktop modes
| Mode | Default shortcut | Behavior |
|---|---|---|
| Speech-to-Text | Ctrl+Alt+Space | Record local speech and insert the transcript into the focused application. |
| Text-to-Speech | Ctrl+Alt+S | Capture the current text selection and read it through the local TTS engine. |
| Converse | Ctrl+Alt+C | Listen, transcribe, call the active LLM profile, stream the reply into TTS, and listen for another turn. |
The tray menu exposes the active LLM profile, profile switching, configuration reload, Settings, last-response copy, logs, About, and Quit. In normal tray mode no permanent main window is required.
Ending or interrupting Converse
Use the Converse hotkey again, remain silent through the configured timeout, or say a configured goodbye phrase. Voice interruption can stop a reply mid-playback; headphones are strongly recommended so the microphone does not mistake speaker output for a new command.
LLM profiles
A profile represents an OpenAI-compatible endpoint, its label, API base URL, optional key, selected model, and optional session header. Use profiles to separate local servers, LAN machines, and remote providers.
llm:
active: local-lm-studio
profiles:
local-lm-studio:
label: "LM Studio (local)"
api_base: "http://localhost:1234/v1"
api_key: ""
default_model: ""
session_header: ""Pro adds a per-profile system prompt/persona and persistent session context. OSS supports profile switching and session headers for the current application session.
CLI and bridge
avrvx --listen
avrvx --speak "Literal text"
printf '%s' "Piped text" | avrvx --speak
avrvx --versionavrvx --synthesize --text-file /tmp/reply.txt --output /tmp/reply.wav
avrvx --synthesize --text-file /tmp/reply.txt --output -
avrvx --transcribe /tmp/voice-message.ogg
avrvx --capabilities
avrvx --daemonThe warm daemon serves newline-delimited JSON over $XDG_RUNTIME_DIR/avervox/bridge.sock. The socket is private to the current user. Integrations can try the daemon first and fall back to a one-shot process.
Configuration
The main configuration file is ~/.config/avervox/config.yaml. Most users can use Settings, then reload the configuration from the tray without restarting or losing the current state.
| Area | Examples |
|---|---|
| Hotkeys | Listen, selection TTS, Converse |
| STT | Model size, language, CPU/CUDA choice |
| Audio | VAD aggressiveness, device behavior |
| Dictation | Interim pause timing |
| Converse | End-of-turn, silence, re-arm, interruption, goodbye phrases |
| Desktop backends | xdotool, ydotool, xclip, xsel, wl-paste |
| LLM | Profiles, model, API base, key, session header |
Pro can save local conversation transcripts under ~/.local/share/avervox/transcripts/ and dictation logs under ~/.local/share/avervox/dictation/. Both can be disabled in configuration.
Integrations
avrvx --install-integration hermes
avrvx --install-integration openclawHermes uses the published avervox-hermes Python package. OpenClaw uses @avervox/openclaw-plugin, published through npm and ClawHub. See the dedicated integration pages for current compatibility and security notes.
Failure behavior
Voice UX needs bounded waits. The current OSS documentation identifies these default thresholds:
| Check | Default | Meaning |
|---|---|---|
| First-token timeout | 30 seconds | No usable content token after the request is sent; empty keepalive events do not count. |
| Empty response | 30 seconds minimum | The stream finishes with no usable content after a sufficiently long wait. |
| Stream read stall | 90 seconds | No stream bytes arrive and the connection appears hung. |
On a detected model failure, AverVOX can abort the request, attempt model unloading for supported servers, disable that model for the current session, and suggest another enabled model. Restarting clears the temporary disabled-model state.
Compatibility and support
The documented baseline is Linux Mint 21/22 or Ubuntu 22.04/24.04, X11 or XWayland, PulseAudio or PipeWire, and Python 3.12+ for OSS. Pure Wayland is best-effort. The current Pro package targets x86_64.
For OSS, open a GitHub issue with the distribution, session type, desktop, version, audio stack, target application, insertion backend, reproduction steps, and relevant logs. Licensed Pro customers may email support@avervoxpro.com.