# Install Zerus
[Product overview](../README.md) | [Detailed reference](reference.md#installation)
Zerus runs on Linux and macOS. Arch Linux x86_64 users can install the complete
CLI and desktop bundle from AUR; Apple Silicon Macs can use the Homebrew cask.
Other installations build from source. The CLI keeps the name `hgs`; the desktop
executable is `hgs-tray`. Windows has a portable [control console](#windows) for
remote Linux and macOS machines; it can also run agents on the Windows computer
itself.
## Requirements
For the CLI: the newest stable Rust, a C compiler, Python 3, tmux 3.7+ and OpenSSH. Install the
agents you want to use on the machines where they will run.
The ADE's verified answer/message delivery needs tmux 3.7's input-mode inspection.
Some distributions ship older tmux packages; use a supported upstream release.
Installing a newer binary does not replace an already running tmux server. Check
the server with `tmux display-message -p '#{version}'`; schedule any server
migration deliberately after saving your sessions. Never kill a live server or
native agents as part of a Zerus GUI/package update.
[Official tmux releases](https://github.com/tmux/tmux/releases).
For the Linux desktop: Rust, Node.js/npm, GTK3, WebKitGTK 4.1, ALSA and
GStreamer. The source installer and AUR packages build Zerus Next by default;
standard autostart uses user systemd. Linux/macOS Qt builds and explicit Qt
installer selections are retired. Existing Qt state remains read-only migration
input; do not delete it. The Mac source route builds Next on macOS 14 or later.
## Local installation
```sh
git clone https://github.com/ufna/zerus.git
cd zerus
./install.sh
./tray/install.sh
```
On macOS, install the dependencies first:
```sh
brew install rust python tmux node pkg-config gstreamer gst-plugins-base
```
The macOS source installer also needs a valid application-signing certificate
and its private key in your keychain. It selects a certificate compatible with
the installed app, including its team and distribution class. For a first install
it prefers Developer ID Application, then Apple Development. If selection is
ambiguous, choose an exact name or SHA-1 fingerprint from
`security find-identity -v -p codesigning` with `HGS_MACOS_SIGN_IDENTITY`:
```sh
HGS_MACOS_SIGN_IDENTITY='Developer ID Application: Example (ABCDE12345)' ./tray/install.sh
```
Compatible certificate signatures keep the privacy identity across local
rebuilds. The installer verifies both designated requirements before replacing
an existing certificate-signed app and stops if they are incompatible. It never
falls back to ad hoc signing. Moving from an older ad hoc installation can require
fresh consent once; no permissions are reset automatically. Source builds use
Tauri and WebKit and are signed locally without notarization;
use the published app for distribution. See [macOS signing](macos-distribution.md#local-source-builds).
On Arch Linux, install the Next build and runtime dependencies before a source
install (AUR recipes declare them automatically):
```sh
sudo pacman -S --needed base-devel rust nodejs npm python tmux openssh \
webkit2gtk-4.1 gtk3 alsa-lib libappindicator dbus gstreamer gst-plugins-base-libs \
gst-plugins-base gst-plugins-good gst-plugins-bad gst-plugins-ugly gst-libav
```
GStreamer supplies the camera, H.264/AAC encoding and media playback plugins.
See [Linux packages and source installation](linux-distribution.md).
The desktop starts in English on every operating system. Settings > Appearance >
Interface language offers an optional Russian preview; restart only Zerus to
apply it. Agent sessions keep running, and untranslated text stays in English.
See [translation coverage and maintenance](../tray/translations/README.md).
Add `~/.local/bin` to `PATH`. The CLI installs to `~/.local/bin/hgs`; SSH calls
use that exact path. The desktop installs to `~/.local/bin/hgs-tray` on Linux or
`~/Applications/hgs-tray.app` on macOS. The installer configures autostart through
systemd or launchd.
On Linux, a normal Next source install also registers `hgs-desktop.service`
from the selected CLI's definition. For AUR packages, run
`zerus-setup --desktop-service` as the desktop user. Startup imports the current
graphical-session environment before creating the backend child; a headless
registration waits for the next graphical login. UI-only updates keep an
unchanged backend alive. Deliberate source CLI upgrades refresh only an already
managed desktop registration; a CLI-only installation creates no new service.
Pacman upgrades never change user services. See the
[Linux background-service commands and bare-WM setup](linux-distribution.md#desktop-background-service).
IPC readiness and background worker ownership are separate; registration alone
does not enable background workers.
On Linux and macOS, Zerus Next defaults to the Service consumer when
`ZERUS_CLIENT_DESKTOP_SERVICE` is absent and the maintained helper's read-only
status confirms an owned registration. An unregistered or unconfirmed host
keeps guarded Native startup. AUR packages and macOS app/cask installation do
not register a user service: run `zerus-setup --desktop-service` on Linux,
or plain `zerus-setup` on macOS, before expecting this default. An existing
background installation keeps its mode. The paired backend is prepared before the GUI; a fresh native
Service Grant admits activation of a newly installed implicit passive service.
An explicit passive choice or retained revoke instead offers **Resume background
work**. One explicit Resume performs the required Rearm and maintained background
selection. Automatic reconnect never repeats those actions. `=0` requests the
guarded Native/rollback path; it cannot override ownership or drain checks.
Windows stays explicit `=1` opt-in. Helper refusal, Grant timeout and service-crash
recovery remain usable through the explicit actions in
[Service consumer activation](desktop-consumer-activation.md).
For a persistent desktop rollback use that page's maintained previous-version
Qt route; an `=0` process override or `launchctl setenv` is not a reboot-persistent
desktop selection.
On Linux, Zerus checks the native AT-SPI accessibility bus before starting GTK.
The check has a two-second budget, including discovery and authentication. If
the bus is unavailable or the check cannot finish, the GUI starts with
`NO_AT_BRIDGE=1` for that launch, avoiding a failed bridge initialization. A
healthy bus keeps accessibility enabled; an explicit `NO_AT_BRIDGE=1` remains
respected. The startup log records `accessibility_bus_unavailable`,
`accessibility_bus_timeout` or `accessibility_probe_failed` without bus addresses.
After the desktop accessibility service recovers, an ordinary GUI restart can
restore accessibility. Zerus does not change accessibility settings or restart
the bus. This startup check cannot prevent a bus failure after the check.
For a local Linux Zerus Next source build, an explicit private WebKitGTK/GTK3
stack can be selected at installation:
```sh
HGS_LINUX_GUI=client HGS_LINUX_WEBKIT_PREFIX=/absolute/private/prefix ./tray/install.sh
```
The prefix must contain `lib/libwebkit2gtk-4.1.so.0`, its JavaScriptCore library,
and the WebKit processes under `libexec/webkit2gtk-4.1`. It uses system GTK3
unless the prefix also contains a `gtk/` override. That override must contain
both GTK3 and GDK3 libraries under `gtk/lib`; a partial override is rejected.
To retain a private WebKit build with system GTK, select a separate prefix
containing only its `lib/` and `libexec/` directories (symlinks are supported).
WebKit still runs its helper processes and injected bundle from the directory
it was installed to, so build each prefix for its final path and keep that
installation in place. The patch set, build commands and qualification checks
for the private arch stack are in the
[WebKitGTK display pacing design](superpowers/specs/2026-10-28-webkitgtk-display-pacing.md#building-the-private-prefix).
The installer saves the selection in `~/.local/share/hgs/local-webkit.json`
(`$HGS_INSTALL_PREFIX/share/hgs/local-webkit.json` for an isolated install).
Later preview installs retain it without the variable. The local service and
desktop entry use `~/.local/libexec/hgs-tray-launch`; it selects these libraries
only for Zerus Next, leaving the real `hgs-tray` binary available
to the maintained updater and its rollback checks. If the stack disappears or
is incomplete, the next launch uses system libraries. Qt and older Zerus Next
rollback builds also use system libraries. Published packages continue using stock WebKitGTK.
Run `HGS_LINUX_WEBKIT_PREFIX= ./tray/install.sh` to clear the selection. Changing
the setting takes effect at the next GUI start; if the binary is unchanged, the
installer leaves the current GUI running. A changed build still uses the normal
draft-preserving update. The opt-in does not modify global library paths or
the environment of native agents. The launcher records the original library
variables; Zerus restores them when starting CLI commands, watches, Terminal
clients, desktop terminals and external applications. WebKit's own subprocesses
keep the private stack.
`HGS_MOBILE_CONNECTOR=1 ./install.sh` also builds the Rust mobile connector
(`services/mobile/connector`) into `~/.local/bin/zerus-mobile-connector`. Later
runs update that copy when it changed; `HGS_MOBILE_CONNECTOR=0` always skips it.
The installer never enables, starts or restarts the connector's service: when the
running service uses the replaced binary, it prints the restart command to run
after phone actions have drained. `mac-install.sh` passes the variable to the
Mac's build. [Connect a computer](mobile-deployment.md#connect-a-computer) sets up
its service, and [Move a computer to the Rust connector](mobile-deployment.md#move-a-computer-to-the-rust-connector)
switches one that runs the Python connector.
To install an already qualified standalone connector without building or updating
the CLI, use `./install.sh --connector-only /absolute/path/to/zerus-mobile-connector SHA256`.
Pass the artifact's verified lowercase SHA256. This mode checks the artifact and
installation directories, replaces only the connector atomically and performs no
service action. `HGS_INSTALL_PREFIX` selects the prefix as usual. Coordinate any
subsequent connector service transition separately; the running process retains
its previous executable until it exits.
Open the workspace from the command line:
```sh
hgs-tray --sessions # Linux
~/Applications/hgs-tray.app/Contents/MacOS/hgs-tray --sessions # macOS
```
The repository's `tmux.conf` is a suggested configuration. If you already have
your own, merge the settings you need manually: `hgs` uses the machine's shared
tmux server.
## Arch Linux
Choose one package; all include the CLI and desktop and conflict with one another:
| Package | Installation | Contents |
| --- | --- | --- |
| [zerus-ade-bin](https://aur.archlinux.org/packages/zerus-ade-bin) | `yay -S zerus-ade-bin` | Stable prebuilt Arch x86_64 bundle |
| [zerus](https://aur.archlinux.org/packages/zerus) | `yay -S zerus` | Stable release compiled locally |
| [zerus-git](https://aur.archlinux.org/packages/zerus-git) | `yay -S zerus-git` | Current upstream main compiled locally |
| [zerus-ade-nightly-bin](https://aur.archlinux.org/packages/zerus-ade-nightly-bin) | `yay -S zerus-ade-nightly-bin` | Prebuilt nightly after full Linux/Arch/macOS/Windows checks |
Keep Arch fully updated before installing. Binary library version requirements
come from the verified release builder; source packages compile against your
installed libraries. The [0.42.0 release](https://github.com/ufna/zerus/releases/tag/v0.42.0)
includes immutable source/binary archives, checked pacman packages, AUR recipes
and SHA-256 checksums. Native agents are installed separately.
Nightly packages update through ordinary `yay -Syu`; source-based `zerus-git`
updates need `yay -Syu --devel`. Nightly releases use immutable build URLs and
checksums and leave the latest stable release unchanged. See
[automatic nightly publication](ci-and-aur.md#automatic-nightly-publication).
After installation, run this once as your normal user, **without sudo**:
```sh
zerus-setup
```
It creates the `~/.local/bin/hgs` compatibility links used by SSH. Existing
source-install files are preserved: inspect and move them aside deliberately if
you want to migrate to the system package. Keep your configuration and agent state.
Services and autostart are opt-in. Inspect old user unit files before enabling
packaged services; local definitions can shadow the system package. Package
installation and upgrades do not restart native agents, tmux or the GUI.
[Service setup and migration](ci-and-aur.md#package-contents-and-compatibility).
## macOS (DMG)
For Apple Silicon Macs running macOS 14 or later, download
`zerus-VERSION-macos-arm64.dmg` from the [latest stable release](https://github.com/ufna/zerus/releases/latest)
or a selected [nightly release](https://github.com/ufna/zerus/releases?q=nightly-&expanded=true).
Open the image, drag **Zerus** into **Applications**, then eject the image and
open Zerus from Applications. The application and disk image are signed with
Developer ID and notarized by Apple. Signed stable macOS downloads begin with
[0.43.0](https://github.com/ufna/zerus/releases/tag/v0.43.0), and nightly downloads with
[nightly 0.42.2.r1291.g5d2e5d0.n17](https://github.com/ufna/zerus/releases/tag/nightly-38794972859);
older releases may not contain a macOS download.
To use the bundled CLI and SSH session bridge, run the per-user setup once,
without sudo:
```sh
/Applications/Zerus.app/Contents/Resources/bin/zerus-setup
```
Local tmux sessions require `tmux` (`brew install tmux`). Agent providers are
installed separately. The Homebrew cask below installs tmux and links the CLI
automatically. For a manual upgrade, quit Zerus from its menu, replace the app
with the new DMG's copy and open Zerus again; native agents keep running.
**Settings > Updates** checks the selected channel and offers **Download DMG**
with replacement instructions. Dev DMGs come from the verified
[desktop Dev catalog](https://zerus.dev/updates/v2/desktop/dev.json) on zerus.dev;
stable and nightly DMGs come from GitHub Releases. Updates are installed manually.
## macOS (Homebrew)
Apple Silicon Macs running macOS 14 or later can install the signed and notarized
application and CLI from the Zerus tap:
```sh
brew install --cask ufna/zerus/zerus
zerus-setup
```
The tap supports three channels. `zerus` follows stable releases; `zerus@nightly` follows
the daily build from main that passed the full CI, published at the same time as
the AUR nightly. `zerus@dev` follows successful main CI builds, with the same
Apple signature and notarization. All install the same `Zerus.app`, so only one can be installed.
Settings, agents and conversations are shared. Switch between Stable and Nightly with:
```sh
brew uninstall --cask zerus && brew install --cask ufna/zerus/zerus@nightly
brew uninstall --cask zerus@nightly && brew install --cask ufna/zerus/zerus
```
For Dev, install `brew install --cask ufna/zerus/zerus@dev`. To switch from nightly:
```sh
brew uninstall --cask zerus@nightly && brew install --cask ufna/zerus/zerus@dev
```
Zerus checks its installed channel unless you choose another one in
**Settings > Updates**. That page shows the complete installed version, a copyable
Homebrew update/channel-switch command and a separate DMG download.
The cask installs `/Applications/Zerus.app`, links `hgs` and `zerus-setup` into
Homebrew's `bin` directory and installs `tmux` as a dependency. It starts nothing
and does not write to your home directory. Run `zerus-setup` once as your normal
user, **without sudo**. It links `~/.local/bin/hgs` for SSH protocols and installs
the on-demand session bridge that lets agents started over SSH use your login
Keychain. Options:
```sh
zerus-setup --autostart # start Zerus at login
zerus-setup --workers # recovery and swarm background workers
```
Through 0.42.2, `--autostart` wrote a LaunchAgent that launchd runs as a background
daemon: whenever other programs keep every core busy, the Zerus window stops
responding and is restarted after 30 seconds. A Zerus that its login item started at
background priority shows **Fix login item** in the Sessions window's status bar.
Nothing changes until you choose: **Update Only** (the default) runs
`zerus-setup --autostart` and applies at your next login while Zerus keeps running;
**Update and Restart** also quits and reopens Zerus now. Saved drafts, sessions and
agents stay; a voice or video message that is still recording stops and is not
kept. You can also run `zerus-setup --autostart` again yourself. It applies at your
next login; to apply it now, quit Zerus from its menu and reload the agent:
```sh
launchctl bootout "gui/$(id -u)/com.hgdev.hgs-tray"
launchctl bootstrap "gui/$(id -u)" ~/Library/LaunchAgents/com.hgdev.hgs-tray.plist
```
`brew upgrade --cask zerus` (or the installed nightly/dev cask) replaces the application but never
quits it, unloads its LaunchAgents or stops tmux and native agents. When the
installed bundle is another build than the running GUI, Zerus shows **Restart to
finish update**; drafts are kept. Background workers finish their current round
and exit when an upgrade replaces their executable, and launchd starts the new
version. A worker that `launchctl print "gui/$(id -u)/com.hgdev.hgs-swarm"` shows
without a `pid` and with `last exit code = 78: EX_CONFIG` cannot be started: the
system log reports `Unable to get updated LWCR`, a launch constraint from its Login
Items record that names an earlier build, which launchd's retries do not renew. Running
`zerus-setup --workers` (or `install.sh` for a source installation) again loads such
a worker again, as does:
```sh
launchctl bootout "gui/$(id -u)/com.hgdev.hgs-swarm"
launchctl bootstrap "gui/$(id -u)" ~/Library/LaunchAgents/com.hgdev.hgs-swarm.plist
```
Use `com.hgdev.hgs-recovery` the same way.
To uninstall, remove the per-user integration first:
```sh
zerus-setup --remove
brew uninstall --cask zerus # use zerus@nightly for Nightly, or zerus@dev for Dev
```
`brew uninstall --zap --cask zerus` (or `zerus@nightly` / `zerus@dev`) additionally removes the Zerus LaunchAgents,
including ones created by a source installation, the logs and saved window state.
`~/.config/hgs`, agent state and conversations are never removed.
### Migrating from a source installation
`zerus-setup` changes nothing while it finds a source installation:
`~/Applications/hgs-tray.app`, a regular file at `~/.local/bin/hgs`, or Zerus
LaunchAgents that run a program outside `/Applications/Zerus.app`. Keep your
configuration and agent state, then migrate deliberately:
1. Quit Zerus from its menu bar icon. Native agents and tmux keep running.
2. Unload the old agents, ignoring ones you never installed:
```sh
for label in com.hgdev.hgs-tray com.hgdev.hgs-recovery com.hgdev.hgs-swarm com.hgdev.hgs.user-session; do
launchctl bootout "gui/$(id -u)/$label" 2>/dev/null || true
done
```
3. Move `~/Applications/hgs-tray.app`, `~/.local/bin/hgs`, `~/.local/bin/hgs_state.py`
and the matching `~/Library/LaunchAgents/com.hgdev.hgs*.plist` files into a
backup folder.
4. Run `zerus-setup` with the options you used before.
To return to the source installation, run `zerus-setup --remove` and restore the
backup.
## Windows
Stable releases after 0.42.2 and nightly releases include a portable Windows
x86_64 zip with the desktop app (`hgs-tray.exe`) and the CLI (`hgs.exe`). It starts
as a control console: it manages agent sessions on your Linux and macOS machines
through the Windows OpenSSH client. You can also
[enable local sessions](#local-sessions-on-windows), and agents then run on the
Windows computer itself, in a session host of your user account on ConPTY, without
WSL ([Windows plan](superpowers/specs/2026-10-10-windows-support-design.md),
[session host](superpowers/specs/2026-10-13-windows-native-host-design.md)).
Requirements:
- Windows 10 version 1903 or later, or Windows 11, on x86_64. Local sessions are
tested on Windows 11 and on the Windows Server 2025 CI runners.
- Zerus Next packages require the [Microsoft Edge WebView2 Evergreen Runtime](https://developer.microsoft.com/microsoft-edge/webview2/).
Winget installs this dependency. For portable/manual installs, install it first
if absent; Microsoft Edge itself is not a substitute. Zerus does not remove
this shared runtime when uninstalled.
- For remote machines, the OpenSSH client. `ssh -V` in PowerShell shows whether it
is installed; otherwise add **OpenSSH Client** in Settings → Optional features.
- For remote machines, at least one Linux or macOS machine with `hgs` installed at
`~/.local/bin/hgs` (see [local installation](#local-installation)) and key-based
SSH access from Windows. Status polls run SSH in batch mode, so the key must work
without a passphrase prompt, for example through the Windows `ssh-agent` service
(disabled by default; enabling it needs an administrator). Host aliases from
`%USERPROFILE%\.ssh\config` work as usual.
- For local sessions, the agents you want to run, installed on the Windows
computer ([below](#local-sessions-on-windows)).
Install and start:
1. From the [latest stable release](https://github.com/ufna/zerus/releases/latest)
or a [nightly release](https://github.com/ufna/zerus/releases?q=nightly-&expanded=true),
download `zerus--windows-x86_64.zip` and `SHA256SUMS`. Each release
carries the zip its own CI run tested; stable 0.42.2 and earlier have none.
2. Check the zip in PowerShell. Both commands must show the same hash
(`Get-FileHash` prints it in upper case):
```powershell
Get-FileHash .\zerus--windows-x86_64.zip -Algorithm SHA256
Select-String -Path .\SHA256SUMS -Pattern windows-x86_64.zip
```
3. Extract the whole zip and run `zerus-windows-x86_64\hgs-tray.exe`. Keep the
files together: the app uses the `hgs.exe` next to it. The executables are not
code-signed, so SmartScreen may show **Windows protected your PC** on the first
start; choose **More info → Run anyway** only for a zip whose hash matched.
The Zerus window opens. Closing it keeps Zerus running in the notification
area, where Windows 11 first hides a new icon behind the **^** arrow; run
`hgs-tray.exe` again to bring the window back.
Alternatively, download `zerus--windows-x86_64-setup.exe` from the
same Stable or Nightly release, verify its own `SHA256SUMS` entry and run it
as your normal desktop user. The per-user installer contains the same tested
ZIP payload, checks the WebView2 prerequisite, installs only into an empty
folder or its own earlier installation (it refuses a folder that holds other
files, such as an extracted zip; keep a portable copy in its own folder) and
offers **Start Zerus at login**, off by default. It preserves configuration,
drafts and native host images when upgrading. Its login choice applies only
to the desktop app; local agent hosting remains a separate opt-in. Service
setup invokes the maintained passive registration command, then registers the
owned Windows Toast identity. Neither step starts the service or grants
background consent. UI-only uninstall removes the separate UI login entry
and preserves the staged CLI, service task and Toast identity.
4. To manage remote machines, add them in **Machines**. Accept a new host key once
with **Open SSH terminal**, then use **Test connection**.
**Install / update HGS…** builds `hgs` on the remote machine from a Zerus source
checkout on this computer; the remote machine needs the
[CLI requirements](#requirements). A checkout whose `install.sh` or
`hgs_state.py` has CRLF line endings is refused.
In PowerShell, run the CLI from the folder with `.\hgs.exe` and quote a machine
argument, because `@` is special there: `.\hgs.exe '@build-01' ls`. Commands
copied from the desktop are quoted for PowerShell the same way. From Git Bash, set
`MSYS_NO_PATHCONV=1` before passing remote paths such as `/workspace/orbit`;
otherwise Git Bash rewrites them into Windows paths.
Configuration and state use the same layout as on Linux and macOS under
`%USERPROFILE%`, or under `HOME` when it is set: `.config\hgs` holds `config`,
`machines.local.json` and `tray.conf`, and `.local\state\hgs` holds the CLI state.
`HGS_CONFIG_DIR` and `HGS_STATE_DIR` move only the CLI's configuration and state;
the desktop app always reads `tray.conf` from `.config\hgs` under `HOME`, or
else under the account's profile folder, whatever `USERPROFILE` says. Desktop
settings are in `%APPDATA%\hgdev\hgs-tray.ini`, and drafts in the
`hgs-tray.ini.drafts` folder next to it. The computer's name in the fleet is
`HGS_SELF` when set, otherwise its lowercase `COMPUTERNAME`.
### Local sessions on Windows
Local sessions stay off until you enable them. Open **Machines** (**Open
Machines** in New session while no computer is available), select this computer
(*This computer: control console*) and choose **Enable local sessions**, or run
`.\hgs.exe session-host install` in the extracted folder. Either way, `hgs`
stages these files in your profile (under `HOME` instead when it is set):
- `%USERPROFILE%\.local\bin\hgs.exe`, the stable CLI that sessions, agent hooks and
the recovery worker run, so they never depend on the extracted folder;
- `%USERPROFILE%\.local\share\hgs\host\\` with `hgs.exe` and the zip's ConPTY
pair (`conpty.dll`, `OpenConsole.exe`), the image the session host starts from;
- the marker `%USERPROFILE%\.config\hgs\local-sessions`, which alone decides that
local sessions are on (`HGS_CONFIG_DIR` moves it with the configuration).
Zerus then lists this computer's sessions, offers it in New session and Accounts,
and runs the stable CLI from its next start. When Zerus starts from another zip of
the same or a newer version, it first stages that zip's `hgs.exe` again (a small
*Starting Zerus…* note may show meanwhile); running sessions stay in the host that
runs them, and the next host starts from the new image. That start also binds
the zip's app to the stable CLI, so the stable CLI accepts the app as your
Zerus. If you move the folder or extract the same zip elsewhere, the app binds
itself again when it next starts. The app of an older zip is not staged and
stays refused, so start the newest zip you extracted. Running
`.\hgs.exe session-host install` yourself removes the binding until the app
next starts. **Machines** shows the
session host's state for this computer, and `hgs.exe session-host status` reports
the marker, the staged files and the host.
The session host starts with the first launch, resume or fork and exits a few
seconds after its last session has ended; listings never start it. Sessions keep
running when Zerus closes or updates and when the terminal or SSH connection that
started them ends. They end when you sign out of Windows or restart it; tracked
sessions stay saved and can be resumed, as after a reboot on Linux.
Install the agents from **Accounts** with **Install agent…**, or yourself. On
Windows, Codex installs with npm (`npm.cmd`, so Node.js must be installed), and
Claude Code and Kimi Code with their vendors' PowerShell installers (`install.ps1`),
which verify the binaries they download. Zerus looks the agents up on `PATH` (with
`PATHEXT`), adds `%USERPROFILE%\.local\bin`, npm's `%APPDATA%\npm` and Kimi Code's
`%USERPROFILE%\.kimi-code\bin`, and runs the script of an npm command shim with
Node.js directly; other batch files are refused.
- **Claude Code** and **Codex** run tracked, with Zerus hooks in their
configuration. Every automatic CI run tests their
[reviewed](ci-and-aur.md#native-agent-compatibility-and-upstream-review) Windows
builds through the session host, and both were also checked on a Windows 11 PC.
Claude Code before 2.1.296 needs Git for Windows for its hooks: without Git Bash
Zerus refuses to track it, and `HGS_TRACKING=0` runs it untracked.
- **Kimi Code** runs tracked as well. It was checked on a Windows 11 PC and has no
Windows CI suite yet.
- **Run PowerShell** in New session (`hgs sh`) opens an untracked PowerShell 7
(`pwsh`), or Windows PowerShell when PowerShell 7 is missing.
- DeepSeek and OpenCode are not offered for this computer.
Start Zerus and `hgs.exe` without elevation: a session host started from an
elevated terminal refuses every client that is not elevated, Zerus included, with
*the session host on this computer runs elevated*. A host started over SSH runs in
another Windows session, where agents cannot open windows on your desktop, such as
a browser sign-in; Zerus asks before it starts or resumes a session there
(**Launch anyway**).
A session host must not run in a job that ends it early, such as an agent's
sandbox or a terminal that starts it, so `hgs` refuses one that cannot leave such
a job (*the session host runs inside a job that does not let it break away*).
Some desktops run every process in a job, Explorer included; there the host shares
Explorer's job and ends with the desktop at sign-out, as sessions do anyway, and
`hgs.exe session-host status` reports it *in the desktop's job*.
To disable local sessions again, end the sessions on this computer and run
`hgs.exe session-host uninstall`, which refuses while one runs. It removes the
marker, so the computer is a control console again; the staged CLI and host images
stay in place. **Machines** has no button for this. `hgs.exe session-host stop`
stops an idle session host without disabling anything.
### Windows limitations
- Until local sessions are enabled, the computer has no local sessions, agent
accounts or hooks, and `hgs.exe` exits with code 2 for local session commands.
Commands for another machine (`hgs.exe '@build-01' …`) work as on Linux.
- No DeepSeek or OpenCode sessions on the Windows computer, and no DeepSeek Native
UI from Windows: it needs SSH connection sharing, which Windows OpenSSH lacks, so
a DeepSeek session cannot be opened externally either. Its Activity still works;
DeepSeek sessions have no Terminal tab on any platform.
- Voice messages cannot be sent to sessions on the Windows computer.
- Mobile connection runs the bundled Rust connector on this PC. Configure its
HTTPS relay and computer credential, choose Start connector, then refresh
Phones and pair by QR code. No other gateway is needed. After that first
start, Zerus starts the connector each time Zerus starts; Stop connector turns
that off until the next Start connector. Closing the GUI keeps it and native
agents running. See [Windows gateway](mobile-deployment.md#windows-gateway).
The first Windows gateway controls existing local Codex/Claude/Kimi sessions;
mobile creation, folder/worktree/Git/file operations, peer routing and
voice/speech are unavailable. Stop drains the current request and keeps
the independent session host and native agents running. It's refused for a
connector Zerus can't prove it started.
- Other machines cannot connect to the Windows computer as a peer: its local
sessions appear only in Zerus on that computer, and its folders in Projects are
not shared with other machines.
- No installer, code signing or self-update. **Settings → Updates**
starts on the Stable channel; choose Nightly to hear about nightly builds too.
It reports a release with a newer product version than the running zip, with
a link to its release page. Stable 0.42.2 and earlier have no
Windows build, so they are never reported; Dev has none either, so on that
channel it says so and reports no update. To update, quit Zerus from the
tray menu and replace the folder with the new one; configuration and state
stay in your profile. To start Zerus at sign-in, put a shortcut to
`hgs-tray.exe` in the Startup folder (`shell:startup`) and add a space and
`--background` at the end of its **Target** field, so Zerus starts in the
notification area without opening its window.
Zerus Next also has an explicit per-user login registration: turn on
**Settings → About → Start Zerus at login**, or use
`hgs-tray.exe --install-login-item` and `hgs-tray.exe --remove-login-item`
(pass the same `--hgs` selector when registering a custom CLI). It is never
enabled automatically. The setting reads and writes only its own value under
`HKCU\Software\Microsoft\Windows\CurrentVersion\Run`; it doesn't detect or
remove a Startup-folder shortcut. Existing shortcuts remain valid; duplicate
background starts keep the window hidden.
- The separate `hgs desktop` service can be registered for the current user's
next interactive sign-in with `hgs.exe desktop registration install --json`.
Use `hgs.exe desktop registration status --json` to inspect it and
`hgs.exe desktop registration remove --json` to remove only its registration.
These commands never start or stop a running service or native agent. The
task uses `InteractiveToken` and least privilege, never SYSTEM or Session 0;
it runs the passive service with the selected configuration/state paths.
The service runs without a console window: `hgs.exe` declares a detached
console allocation policy, so Windows 11 24H2 and later give it none, and on
earlier releases it releases the console created only for it at startup (a
window may flash briefly at logon). Its helpers and its connections to other
computers in background mode start without windows too, so no terminal window
belongs to the service and closing one never stops it. On 24H2 and later the
same policy means `start hgs …`, a shortcut or another program that starts
`hgs.exe` without a console of its own (CREATE_NEW_CONSOLE or ShellExecute)
gets no console window either; run `hgs` from a terminal to see its output.
Registration does not grant background writer ownership or enable automatic
approvals. An explicit `HGS_EXECUTABLE` is preserved; otherwise installation
stages only the stable `%USERPROFILE%\.local\bin\hgs.exe`, without enabling
local sessions. A foreign or changed task is kept for manual review. If a
command reports an uncertain outcome, inspect `status` before trying again.
This service task is separate from the UI's Startup shortcut or Run value.
Registration uses native Task Scheduler COM in a bounded helper of the same
`hgs.exe`; it does not launch PowerShell or load user scripts. User shell
sessions and vendor installers can still use PowerShell.
The installer owns the Start menu shortcut and gives it the same
`com.hgdev.hgs-tray` AppUserModelID and Toast activator as the native registry
registration. `hgs` does not create or modify shortcuts; portable ZIP users
use the existing registry-based notification registration.
- For service-owned Windows alerts, install the passive service registration
first, then run `hgs.exe desktop notification-registration install --json`.
`status --json` reports only registration, not service readiness or delivered
alerts. These commands keep the `com.hgdev.hgs-tray` identity and bind its COM
activation registration to the exact selected stable CLI/configuration. A
foreign, partial or changed registration is kept. The worker never repairs it.
The background service compares that registration with its own running image
and its configuration and state folders, never with a path rebuilt from its
own `HOME`. A task started by Task Scheduler sees the logon environment, which
can differ from the registering shell's: Git Bash and MSYS set their own
`HOME`. This matches the registered command path and arguments; it is not a
content or Grant check. When the registration names another CLI image with
otherwise exact values, attention reports `notification_registration_other_image`
and stays unavailable. It never switches image, reinstalls or retries an
effect. `notification-registration install` refuses an existing registration
for another image (`foreign_or_incomplete_notification_registration_kept`).
Replacing it takes the explicit removal below, then an install from the CLI
the background task runs. After a reinstall to another path, the removal also
takes the registration of the earlier CLI image when it is exactly what this
build writes for that image with the same configuration and state folders;
the reply then reports `previous_image: true`. Another configuration or state,
an older registration format, extra or missing values or keys never qualify.
The earlier image is only compared, never started or read.
The three current-user keys are `HKCU\Software\Classes\AppUserModelId\com.hgdev.hgs-tray`,
`HKCU\Software\Classes\CLSID\{0F0F70A2-1D40-47D8-AC5E-D6A9B789605F}`,
and `HKCU\Software\Classes\CLSID\{0F0F70A2-1D40-47D8-AC5E-D6A9B789605F}\LocalServer32`.
After an interrupted install, inspect all three before manually removing
only an owned partial set; the
commands refuse partial sets rather than repairing or deleting them.
Cold COM activation is passive and refuses without acquiring a service owner.
Root service attachment and native alert/click acceptance remain separate.
UI-only uninstall preserves this backend registration. Explicit backend
removal uses one sequence in passive and background mode alike, with a fresh
UUID retained for the whole operation:
1. `hgs.exe desktop revoke --json --request-id UUID --reason rollback`, until it
reports accepted, durable, revoked and checkpointed.
2. Stop the running service through its owner: end only the running
`hgs-desktop` task in Task Scheduler. Never end other processes.
3. `hgs.exe desktop registration remove --json`, so the task no longer starts at
sign-in. It does not stop a running service: when step 2 is not possible,
run this step first, then sign out of Windows and back in.
4. `hgs.exe desktop notification-registration remove --json --request-id UUID`
with that **same** UUID.
The Toast command removes only while no service runs: it holds the service's
own lock and handoff lock until the registry change is done. Without desktop
state nothing more is needed. With existing state it needs the CURRENT
settled rollback of that exact UUID: the newest command, the writer still
revoked under that rollback, any handoff marker revoked for the same writer,
and no undrained operation. A later grant, mode change, handoff or another
revoke supersedes it; start again with a new UUID. The command never issues,
resumes or replays a revoke, and never migrates, checkpoints or deletes state.
Busy, changed, missing, pending or unknown evidence keeps the registration.
While the service runs, removal still refuses until the Windows Runtime drain
attachment is integrated. Toasts already in the notification center may stay;
removal does not withdraw them.
- Without SSH connection sharing, every poll of every machine is a full SSH
handshake: about 150 ms per machine on a LAN. The app lists this computer at
most once every 15 seconds, or every 5 seconds with local sessions enabled.
[Windows details in the reference](reference.md#windows) |
[Building on Windows](../CONTRIBUTING.md#windows)
## Checking for updates
Open **Settings > Updates** to see the installed and published desktop versions,
the last successful check and any check error. **Update checks** contains the
automatic-check switch, release channel and **Check now** action. Automatic
checks run at most once a day for Stable/Nightly and every 15 minutes for Dev; manual checks remain available when
automatic checks are disabled.
When a newer release is verified, the workspace shows a compact **New version**
button with the Zerus mark. Its tooltip identifies Zerus and the release version;
clicking it opens Updates. The tray menu also offers Updates, and fresh newer
releases can show a system notification.
**View release** opens the published release page. Expand **Show installation
details** for package ownership and copyable Arch or Homebrew commands. Mac
downloads also offer a DMG button and manual replacement instructions. There, **Installation
instructions** opens this guide at the section for your system:
[Arch Linux](#arch-linux) on Arch-based Linux, [local installation](#local-installation)
on other Linux systems, [Homebrew](#macos-homebrew) on macOS and [Windows](#windows)
on Windows. These actions do not install an update automatically. A local build
remains separate from an optional AUR installation.
## Other machines
Add an SSH connection in **Machines**. The agent's machine needs `hgs` installed
at `~/.local/bin/hgs`, the selected agent and the project folder. SSH settings and
keys stay local.
To install on a Mac from another machine:
```sh
./mac-install.sh # CLI and Zerus Next
./mac-install.sh --no-tray # CLI only
```
Fresh installs and upgrades use Zerus Next, including upgrades from Qt.
Qt installer selections are refused. The maintained updater preserves drafts and
one usable previous Next build. Each displaced Qt rollback image gets a unique
entry under `desktop-qt-legacy/qt-*/` beside `desktop-previous`; older versions
can coexist. These are manual recovery only and are never offered by `--rollback`
or deleted. An archive-move failure keeps the image named and retained while the
verified Next update completes its remaining checks. Qt's settings export stays
at its existing compatible path.
Desktop signing uses the Mac's existing keychain. An optional
`HGS_MACOS_SIGN_IDENTITY` selector is forwarded to the remote installer; private
keys and signing credentials are never copied from the calling machine.
The CLI configuration lives at `~/.config/hgs/config`. For terminal use, you can
set SSH aliases directly:
```sh
HGS_SELF="workstation"
HGS_PEERS="macbook build-01"
```
Use **Projects** to collect folders from different machines into one project.
The shared project catalog syncs between connected members; local SSH access is
managed in **Machines**.
## Agents
Use **Accounts** to configure accounts and install supported agents.
On Arch, installing Codex or DeepSeek from Accounts requires both the optional
`nodejs` and `npm` packages. For a fresh npm setup, choose a writable user prefix
before installing agents; Zerus already recognizes `~/.local/bin`:
```sh
sudo pacman -S --needed nodejs npm
npm config set prefix "$HOME/.local"
```
Keep an existing working npm prefix if you already manage native agents there.
The current official DeepSeek Harness adapter is pinned to
`@deepseek-ai/dsh@0.2.2-rc.1`. That release still pins
`@modelcontextprotocol/client` 2.2.0 and a nested fflate 0.8.2, so apply the
reviewed security overrides in DSH's own package root:
```sh
npm install -g @deepseek-ai/dsh@0.2.2-rc.1
npm pkg set --prefix "$(npm root -g)/@deepseek-ai/dsh" \
'overrides.@modelcontextprotocol/client=2.3.0' 'overrides.fflate=0.8.3'
npm install --omit=dev --prefix "$(npm root -g)/@deepseek-ai/dsh"
hgs account login native-dsh
```
The last two commands also apply to an existing 0.2.2-rc.1 installation. They
change only DSH's package manifest and dependency lock, not other agents in a
shared npm prefix. A bare global install retains the cross-origin redirect and
malformed-ZIP64 denial-of-service vulnerabilities. These two overrides do not
suppress other dependency alerts or guarantee a clean audit; keep reviewing
other upstream advisories normally.
Then choose **DeepSeek Harness** in **New session**.
[Adapter capabilities and limitations](reference.md#deepseek).
See the [reference](reference.md) for commands and operational details, and
[CONTRIBUTING.md](../CONTRIBUTING.md) for build checks.