hermes - 💡(How to fix) Fix installer: SSH/HTTPS clone both fail on restricted networks; ZIP fallback should be first-class

Summary

On Windows + networks where github.com:443 is unreachable (corporate firewalls, GFW, captive portals, regional ISP blocks), the Windows PowerShell installer fails both git clone attempts before falling back to ZIP. The ZIP path is the only one that works, but it's a last-resort branch with weaker post-conditions than the git path — and on my install, the run that finally succeeded only succeeded because ZIP worked. I'd like to argue for making ZIP the default on Windows, not the fallback.

Environment

• OS: Windows 11 Pro (10.0.26200)
• Git for Windows: 2.53.0.windows.1
• Python: 3.11.15 (managed by uv)
• Installer script: scripts/install.ps1 (downloaded from main on 2026-06-05)
• Network: HTTPS to github.com blocked; HTTPS to codeload.github.com works

Reproduction

Run the canonical Windows one-liner on a machine where github.com:443 is blocked:

iex (irm https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.ps1)

Observed behavior (from bootstrap-installer.log)

Step 1 — SSH clone fails

-> Trying SSH clone...
Cloning into 'C:\Users\Milk\AppData\Local\hermes\hermes-agent'...
fatal: unable to access 'https://github.com/NousResearch/hermes-agent.git/': Connection timed out after 300047 milliseconds

(The SSH URL is rewritten to HTTPS by the system Git config, then the HTTPS request times out — that 300s wait is wasted on every restricted-network install.)

Step 2 — HTTPS clone fails

-> SSH failed, trying HTTPS...
Cloning into 'C:\Users\Milk\AppData\Local\hermes\hermes-agent'...
fatal: unable to access 'https://github.com/NousResearch/hermes-agent.git/': Failed to connect to github.com port 443 after 21228 ms: Could not connect to server

Step 3 — ZIP fallback succeeds

[!] Git clone failed -- downloading ZIP archive instead...
[OK] Downloaded and extracted
Initialized empty Git repository in C:/Users/Milk/AppData/Local/hermes/hermes-agent/.git/
[OK] Git repo initialized for future updates
-> Initializing submodules...
[OK] Submodules ready
[OK] Repository ready

The ZIP branch uses codeload.github.com (different SNI / different rate-limit pool), which is reachable on networks that block github.com. On this install, ZIP was the only path that worked, and the installer completed all 16 stages successfully.

Separate but related bug: update branch locks user in a zombie state

In scripts/install.ps1 around the repository stage update path (the if ($repoValid) branch that runs after a previous run left an existing $InstallDir):

if ($repoValid) {
    git fetch origin
    git checkout $Branch     # <-- no clean, no reset
    git pull origin $Branch
} else {
    # fall through to fresh clone
    Remove-Item -Recurse -Force $InstallDir
}

If a prior run was killed mid-clone (or hit a curl 56 schannel: server closed abruptly / connection error before the git checkout completed), the directory is left with a partial .git/ (a populated FETCH_HEAD and remotes/origin/* refs, but no refs/heads/<Branch> local branch) and a working tree full of untracked files (every file in main). The $repoValid check sees a .git/ and returns true, so the installer enters the update branch. git fetch succeeds (FETCH_HEAD refreshes), but git checkout main aborts with:

error: The following untracked working tree files would be overwritten by checkout:
    .dockerignore
    .env.example
    ... (200+ files)
Aborting
fatal: early EOF

…and the user is stuck in an infinite loop until they manually rm -rf $InstallDir. This is what I had to do before ZIP saved me.

Proposed changes

For the network issue

1. Try ZIP first on Windows (or in parallel with the git clones). codeload.github.com is reachable on a much wider set of networks than github.com:443, ZIP is faster, and it side-steps the entire class of Windows/Schannel/curl-56 issues (curl 56 schannel: server closed abruptly (missing close_notify)) that intermittently break git clone even on networks that can reach GitHub.
2. If keeping the git path as primary, at least reorder the timeout: probing HTTPS with a 5–10s timeout before SSH would cut the wasted 300s SSH wait. The current order (SSH first, with the system rewriting to HTTPS) makes the SSH branch's only real value (key-based auth on private forks) inaccessible to most users.
3. Add a -Source zip / -Source git flag so users in restricted environments can pin the working path.

For the update-branch bug

Strengthen the repoValid check to require git rev-parse HEAD to succeed (not just FETCH_HEAD to exist), or simply run git clean -fdx before git checkout in the update branch. Either fix removes the zombie-state failure mode.

Workaround (for anyone hitting this right now)

# Wipe the half-installed directory and re-run; the installer will go
# straight to ZIP and succeed.
Remove-Item -Recurse -Force "$env:LOCALAPPDATA\hermes\hermes-agent"

Versioning

scripts/install.ps1 SHA verified from the bootstrap-cache after this install matches what the installer pulled from main on 2026-06-05. Commit SHA can be added if maintainers want a permalink.

Happy to send a PR for either change — just point me at the right test/CI entry points.