Skip to main content

Quick Start

altgo supports Linux (Ubuntu 22.04+) on x86_64 and aarch64, and Windows 10+ on x86_64 and arm64. Linux builds and releases are verified on Ubuntu 22.04. Other distributions may work but are not guaranteed. macOS is not supported.

Transcription has two backends. The local backend embeds sherpa-onnx and offers SenseVoice or FireRedASR2 CTC, so no separate binary is needed and it works offline after the model is downloaded. The online backend sends audio to a cloud ASR endpoint, with MiMo ASR as the default, and does not download a model.

Linux: add your user to the input group before installing​

The current user must be added to the input group, otherwise /dev/input/event* cannot be read and key listening fails. Log out and back in after running:

sudo usermod -aG input "$USER"

End users: finish everything in Settings​

Linux​

  1. Download the package for your system from Releases: .deb (Ubuntu/Debian), .rpm (Fedora/RHEL), or .AppImage.
  2. Complete the input group step above. The .deb and .rpm packages declare the desktop and audio dependencies, so the package manager pulls them in. The AppImage does not resolve dependencies, so install the missing libraries reported at launch.
  3. Start the application and open Settings:
    • Under transcription, choose the local backend and download a model, or choose the online backend and fill in the API key, base URL and model name.
    • Configure polishing, appearance and the trigger key as needed (Press to set).
    • Save.
  4. Results are written to the clipboard and shown in a single line in the overlay window. Paste them into the target application. The full text is available in the history list on the home page, where it can be viewed, copied or polished again.

Windows​

  1. Download the *-setup.exe for your architecture (x64 or arm64) from Releases. This is the NSIS installer.
  2. Run the installer, then start altgo from the Start menu.
  3. Open Settings, choose the transcription backend and finish the model or API configuration, configure polishing and the trigger key, then save.

Windows installers use free code signing provided by SignPath Foundation (onboarding in progress). See the Code signing policy for the full policy and the Privacy Policy for data handling. Until signing is enabled, Windows may show a "Windows protected your PC" prompt and treat the installer as an unrecognized app. This is the standard warning for unsigned programs and does not mean the file is unsafe. To continue, click "More info" and then "Run anyway". Windows 11 with Smart App Control blocks unsigned programs entirely and provides no per-program exception, so the feature must be turned off in Windows Security under "App & browser control".

To check that the downloaded file was not modified, download checksums.txt from the same release and compare its SHA-256 with certutil -hashfile <installer> SHA256.

Do not use "copy configs/altgo.toml and edit it by hand" as the default path. That is an advanced workflow. Regular users only need the UI.

Start​

Run altgo or the executable in the installation directory. Hold the right Alt key to speak, release it and check the result in the overlay window. The trigger key can be changed in Settings.

Offline installation (Windows x64)​

When the target machine has no internet access, both the installer and the models must be moved over. Download a zip from the offline asset release: use altgo-2.7.8-offline-win-x64.zip for Windows 11, or altgo-2.7.8-offline-win-x64-with-webview2.zip for Windows 10 or when you are not sure whether WebView2 is installed.

After extracting, run these steps in order:

  1. Open PowerShell in the extracted directory and run powershell -ExecutionPolicy Bypass -File .\install-offline-assets.ps1. The script first verifies the bundled SHA256SUMS, then copies the models, polish-models and runtime directories to %APPDATA%\altgo, skipping files whose hash matches an existing file. It does not modify altgo.toml or your existing configuration.
  2. On Windows 10, then run webview2\MicrosoftEdgeWebView2RuntimeInstallerX64.exe. Windows 11 ships with WebView2, so skip this step.
  3. Run altgo_2.7.8_x64-setup.exe to install the application, then start it from the Start menu.

The models and runtime take about 650 MB in %APPDATA%\altgo. During the transfer the zip, the extracted directory and the copy in the configuration directory coexist, so peak usage is close to 1.9 GB. Delete the zip and the extracted directory after installation. After starting, select the local sense-voice transcription model and the local polishing engine in Settings. The models are already in place and the UI shows them as downloaded, so no network access is needed.

To check that the zip was not modified, compare its SHA-256 with certutil -hashfile <zip> SHA256 against the value on the asset release page. The script verifies each file inside the package after extraction.

Advanced: only when you edit the configuration file by hand​

Configuration file path: ~/.config/altgo/altgo.toml. Field documentation is in configs/altgo.toml in the main repository.

Developers: build from source​

Build with make build, same as the main repository. Use make build for day-to-day verification as well.

git clone https://github.com/ouyangjiahong26/altgo.git
cd altgo
cd frontend && npm install && cd ..
make build

To iterate on frontend UI quickly, cargo tauri dev can be used temporarily. The full pipeline is still verified with make build.