Installation

Install TermHQ on Windows or macOS, what to expect from SmartScreen and Gatekeeper, and how updates work.

Download the build for your platform from the releases page.

Windows

Run the installer. TermHQ supports Windows 10 and 11.

Because builds are not yet code-signed with an Authenticode certificate, SmartScreen shows a warning the first time you run an installer: “Windows protected your PC.” Choose More info → Run anyway. SmartScreen judges each file separately, so the warning can reappear when you install a new version — same two clicks. Why the warnings →

There is nothing to install alongside it — no runtime, no separate terminal components. TermHQ carries its own copy of the Windows console machinery, which is why terminals render identically on an old Windows 10 build and a current Windows 11 one. Some terminal apps do not, and the difference shows up as duplicated prompt lines in exactly the full-screen tools coding agents use.

macOS

Open the .dmg and drag TermHQ to Applications. Builds are for Apple silicon; there is no Intel build.

From v0.2.3, the app bundle has an ad-hoc signature that macOS can verify for integrity. It is not signed with an Apple Developer ID or notarized by Apple, so Gatekeeper still requires approval. On current macOS (Sequoia and later), use System Settings for the first launch:

1. Open TermHQ once. macOS says it “could not verify this app is free of malware” — dismiss the dialog (don’t choose Move to Trash).
2. Open System Settings → Privacy & Security, scroll down to the Security section, and click Open Anyway next to the TermHQ message.
3. Confirm in the dialog that follows. From then on it opens normally.

On older macOS versions, right-click → Open still offers an “Open” button directly. Why the warnings →

If v0.2.2 says TermHQ is damaged

Download v0.2.3 or later and replace the older TermHQ app in Applications. The v0.2.2 macOS bundle had an incomplete code signature; v0.2.3 fixes that packaging defect. Your settings and saved workspaces live outside the app and are preserved when you replace it. Follow the approval steps above after installing the new version.

Why the install warnings

TermHQ does not yet use verified publisher certificates: the Windows installer has no Authenticode certificate, and the macOS app uses an ad-hoc signature without Apple notarization. The macOS signature seals the app’s contents but does not establish an Apple-verified publisher identity. That is why explicit approval is still required even when the bundle passes signature verification.

Two things worth knowing in the meantime:

• Download only from this site or the releases page — every build is published from an exact tagged commit, so a version always means the same code.
• If a downloaded installer vanishes, an antivirus false positive is the likely cause — unsigned binaries occasionally trip them. The file on the releases page is unchanged; restore it from quarantine or re-download.

Linux

Linux support is pending.

Voice dictation

Dictation runs on local Whisper models: transcription happens on your own machine.

The installers ship without a speech model, which is most of why they are small. The first time you want voice, open Settings → Voice and download a model — one click, a progress bar, done. Until then there is no mic button and nothing voice-related runs: nobody gets handed a hundred-megabyte AI download they did not ask for. On macOS the first recording asks for microphone permission, as any app does.

Four models are offered, from a quick 78 MB English-only one to a 1.6 GB multilingual one — each labeled with its size and language coverage, and the panel says in plain text exactly where every download comes from. Models can be switched, deleted, or re-downloaded at any time, they survive app updates, and if you already have a compatible model file of your own, Import brings it in instead.

Dictation listens in English by default. Settings → Voice has a language dropdown with sixteen more, plus an auto-detect option that lets a multilingual model identify the language per recording.

How dictation works day to day — the mic button, the chord, Hold to talk, where the words land — is on the Dictation page.

Where TermHQ keeps its files

Settings, themes, saved workspaces and a log file live in a per-user configuration directory, along with the pictures and videos you add as backgrounds (backgrounds/) and your saved SSH profiles and recent connections (ssh-profiles.json, which never holds a password or a key):

If config.json there ever cannot be read — a typo in a hand edit, say — TermHQ keeps a copy of it named config.json.broken- plus the time in UTC, such as config.json.broken-2026-09-23T101500Z, starts with default settings, and shows a notice with the reason and a button that opens the folder.

Updating

TermHQ checks for a new release on its own — shortly after launch and every six hours while it runs — and never installs one on its own. A new version shows up in two places: a toast at the bottom left of the window, and Settings → General → Updates. Both have one button, Update and restart; the toast also has Later, which puts that version away until a newer one comes along or the next launch, and What’s new, which opens Settings → General → Updates, where the release notes are.

What the click does, in order: the release is downloaded and its signature checked; any editor with unsaved changes asks you to save or discard, the same protection as closing the window; if terminals are running in any workspace, TermHQ asks Update and restart now? and says how many will end; other TermHQ windows are asked to close and take the same card; then TermHQ closes, the installer runs, and TermHQ reopens in the workspace you were in.

The unsaved-work check happens after the download, so it includes edits you made while waiting. Choose Save all & update, Update without saving, or Cancel. If another window remains open, check it for a save prompt, close it when ready, and try the update again. TermHQ does not force it closed.

The terminals question counts every workspace, not only the window you clicked in, because the restart ends the shells in all of them, along with the commands and agents running there. Cancel has focus, so Enter alone backs out; Update and restart goes ahead.

Update signatures verify that the download comes from TermHQ. They are separate from the operating system’s installer certificates, so the installation warnings described above may still appear.

Your shells restart. The layout, working directories, titles and the stash all come back; commands and agents that were running in those panes are stopped. The toast says so before you click. Your configuration directory is never touched by an update: settings, themes, keyboard shortcuts, favorites, saved workspaces, backgrounds, SSH profiles and speech models all stay exactly as they were.

If a download fails or its signature does not verify, nothing is installed and the app stays as it was; the toast offers to try again. Turn the automatic check off in Settings → General → Updates and “Check now” becomes the only way to look. Installing over the top from a downloaded release works too, and leaves the configuration directory alone just the same.

If TermHQ cannot save the workspace, installation stops before shutting down your shells. If the installer fails after the shells have stopped, the app reports the failure and restores the ability to open terminals for recovery. Previously running commands have still stopped; check your work before retrying.

Uninstalling

Use the platform’s normal uninstall route. The configuration directory above is left in place; delete it by hand if you want TermHQ’s settings, themes, saved workspaces, backgrounds and SSH profiles gone too.