Bug Report: install.ps1 Windows one-line installer fails with PowerShell parser errors due to malformed parameter block

Summary

The Windows PowerShell installer entrypoint for Hermes Agent can fail before any installer logic runs when invoked via the documented one-line command:

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

On affected revisions, PowerShell throws a parser error such as InvalidLeftHandSide / The assignment expression is not valid on the lines defining $Branch, $HermesHome, and $InstallDir, which indicates the script's top-level parameter declarations are malformed rather than being inside a single valid param(...) block.[cite:13][cite:15]

Environment

• OS: Windows (native install path, no WSL)
• Shell: Windows PowerShell
• Installation method: official one-line installer using irm ... | iex
• Hermes documentation context: native Windows is documented as an early beta path, while Hermes still provides Windows-native installation documentation and installer references.[cite:15][cite:76]

Affected command

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

This is the same pattern shown in the script usage comments and in public installation guidance for Hermes Agent.[cite:12][cite:76]

Expected behavior

Running the one-line installer on Windows should download the script and proceed into the installer flow, including checks for uv, Python, Git, Node.js, and repository setup, without PowerShell parse failures.[cite:15]

Actual behavior

The script fails immediately during parsing, before any installer stages execute. A representative error looks like this:

iex : line:18 char:23
+     [string]$Branch = "main",
+                       ~~~~~~
The assignment expression is not valid. The input to an assignment operator
must be an object that is able to accept assignments, such as a variable or a property.

line:19 char:27
+     [string]$HermesHome = "$env:LOCALAPPDATA\hermes",
+                           ~~~~~~~~~~~~~~~~~~~~~~~~~~
The assignment expression is not valid.

line:20 char:27
+     [string]$InstallDir = "$env:LOCALAPPDATA\hermes\hermes-agent",
+                           ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The assignment expression is not valid.

FullyQualifiedErrorId : InvalidLeftHandSide,Microsoft.PowerShell.Commands.InvokeExpressionCommand

This failure pattern is consistent with the open Hermes issue reporting that the one-line installer is broken and emits The assignment expression is not valid rather than entering the normal installation flow.[cite:13]

Root cause analysis

The failure appears to be caused by a malformed top-level parameter declaration in install.ps1.[cite:13] In the broken form, the script's initial parameter list is not wrapped in one valid, contiguous param(...) block; instead, it contains structural issues such as duplicate param( tokens and/or a misplaced closing ) that splits the parameter list.[cite:15]

Because of that malformed structure, PowerShell no longer parses lines like:

[string]$Branch = "main",
[string]$HermesHome = "$env:LOCALAPPDATA\hermes",
[string]$InstallDir = "$env:LOCALAPPDATA\hermes\hermes-agent",

as legal parameter declarations. Instead, the parser treats them as invalid assignment expressions and terminates before any script logic can run.[cite:41][cite:43]

In the observed broken file, the beginning of the script effectively behaved like this in structure:

param(
param(
    [switch]$NoVenv,
    [switch]$SkipSetup,
    [string]$Branch = "main",
    [string]$HermesHome = "$env:LOCALAPPDATA\hermes",
    [string]$InstallDir = "$env:LOCALAPPDATA\hermes\hermes-agent",
    [switch]$Manifest,
    [string]$Stage,
    [switch]$ProtocolVersion,
    [switch]$NonInteractive,
    [switch]$Json,
)

    [string]$Ensure = "",
    [switch]$PostInstall
)

That structure is syntactically invalid in PowerShell because the parameter list is interrupted and the closing parenthesis placement is wrong.[cite:41][cite:43]

Minimal fix

The parameter declarations should be consolidated into one valid param(...) block at the top of the script, before normal executable code begins.[cite:41]

A corrected structure is:

param(
    [switch]$NoVenv,
    [switch]$SkipSetup,
    [string]$Branch = "main",
    [string]$HermesHome = "$env:LOCALAPPDATA\hermes",
    [string]$InstallDir = "$env:LOCALAPPDATA\hermes\hermes-agent",
    [switch]$Manifest,
    [string]$Stage,
    [switch]$ProtocolVersion,
    [switch]$NonInteractive,
    [switch]$Json,
    [string]$Ensure = "",
    [switch]$PostInstall
)

With the malformed duplicate param( removed and the misplaced ) corrected, the script parses and executes normally on Windows, proceeding into the usual dependency and repository setup flow.[cite:41][cite:43]

Reproduction steps

1. Open Windows PowerShell.

2. Run the official one-line installer:

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

3. Observe that PowerShell throws a parser error referencing $Branch, $HermesHome, and $InstallDir, and the installer never starts.[cite:13]

An alternate verification path is:

irm https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.ps1 -OutFile install.ps1
[scriptblock]::Create((Get-Content .\install.ps1 -Raw))

On the broken revision, this also surfaces parser errors tied to the malformed parameter block.[cite:41][cite:43]

Workaround confirmed

A local workaround was successful:

1. Download install.ps1 locally instead of piping it directly into iex.

2. Repair the top-level parameter block so it is one syntactically valid param(...) declaration.

3. Run the script locally with:

   powershell -ExecutionPolicy Bypass -File .\install.ps1

After fixing the malformed param(...) structure, the installer successfully progressed through dependency checks (uv, Python, Git, Node.js, ripgrep, ffmpeg) and repository setup on native Windows.[cite:15]

Additional note observed during install

After the parser bug was fixed, a separate update-time issue was encountered where git pull failed because a local modified file (agent/auxiliary_client.py) would be overwritten by merge. That was resolved by stashing local changes, pulling from origin/main, and reapplying the stash. This appears unrelated to the parser bug and should be treated as a separate issue unless maintainers want the installer to auto-handle dirty working trees more gracefully.[cite:50][cite:62]

Impact

This bug breaks the primary Windows-native installation path at the very first step for affected revisions, making the official one-line installer unusable even on systems that otherwise satisfy Hermes prerequisites.[cite:13][cite:15] Because the failure happens during parsing, users receive no meaningful recovery path from the script itself and may incorrectly assume Hermes does not support their environment.[cite:15][cite:76]

Suggested action

• Fix the top-level parameter block in scripts/install.ps1 so it is a single valid param(...) declaration.[cite:41][cite:43]
• Add a lightweight CI syntax check for the PowerShell installer, for example by parsing the script in Windows PowerShell before release, to catch malformed parameter-block regressions early.[cite:41]
• Optionally document a fallback Windows troubleshooting path that tells users how to download the script locally and validate parsing before execution.[cite:15][cite:76]