{"repo":"NousResearch/hermes-agent","public_id":"16314","display_label":"ARM64 and non-sudo installer fixes","summary":"These issues and PRs address failures in the installation script, specifically around ARM64 architecture support for Playwright and non-sudo service-user installs on apt-based distributions. No resolution status is assumed.","subsystem":"apps/bootstrap-installer","counts":{"members":4,"open_issues":0,"open_issues_distinct":0,"open_prs":1,"closed_issues":1,"merged_prs":1,"attempt_prs":2},"landed_fix":{"status":"merged_to_main","basis":"structural","pr":25814,"merged_at":"2026-05-14T16:05:32+00:00"},"resolution":{"state":"unresolved","by":null},"freshness":{"state":"verified","last_verified_at":"2026-05-14T16:05:32+00:00","is_stale":false},"grouping":{"backbone":"STRUCTURAL_SPANNING","link_density":0.5},"fix_edges":[{"issue_number":16314,"pr_number":25814,"tier":"verified","basis":"superseded_ref","confidence":0.9,"recoverable_from_timeline":false,"pr_merged_at":"2026-05-14T16:05:32+00:00"}],"members":[{"kind":"issue","number":16314,"title":"[Bug]: The browser installation script used on the arm64 architecture server keeps failing to install; could you please adjust it to make the one-click installation script more user-friendly?","url":null,"state":"closed"},{"kind":"pr","number":16343,"title":"fix(installer): add arm64 fallback for Playwright setup","url":null,"state":"open","close_reason":{"category":"uncategorized","implication":"needs_llm"},"merged":false},{"kind":"pr","number":16395,"title":"fix(install): #16314 improve Playwright setup behavior on ARM64","url":null,"state":"closed","close_reason":{"refs":[{"kind":"pr","value":"#25814","number":25814}],"category":"superseded_by_pr","implication":"superseded"},"merged":false},{"kind":"pr","number":25814,"title":"fix(install): support non-sudo service-user installs on apt distros","url":null,"state":"merged","close_reason":{"category":"merged"},"merged":true,"is_fix_pr":true,"fix_tier":"verified","files_changed":["scripts/install.sh","tests/test_install_sh_browser_install.py","website/docs/getting-started/installation.md"],"fix_hunks":[{"file":"scripts/install.sh","hunks":["@@ -69,6 +69,7 @@ DETECTED_BROWSER_EXECUTABLE=\"\"\n # Options\n USE_VENV=true\n RUN_SETUP=true\n+SKIP_BROWSER=false\n BRANCH=\"main\"\n \n # Detect non-interactive mode (e.g. curl | bash)","@@ -91,6 +92,10 @@ while [[ $# -gt 0 ]]; do\n             RUN_SETUP=false\n             shift\n             ;;\n+        --skip-browser|--no-playwright)\n+            SKIP_BROWSER=true\n+            shift\n+            ;;\n         --branch)\n             BRANCH=\"$2\"\n             shift 2","@@ -112,6 +117,7 @@ while [[ $# -gt 0 ]]; do\n             echo \"Options:\"\n             echo \"  --no-venv      Don't create virtual environment\"\n             echo \"  --skip-setup   Skip interactive setup wizard\"\n+            echo \"  --skip-browser Skip Playwright/Chromium install (browser tools won't work)\"\n             echo \"  --branch NAME  Git branch to install (default: main)\"\n             echo \"  --dir PATH     Installation directory\"\n             echo \"                   default (non-root):  ~/.hermes/hermes-agent\"","@@ -1566,6 +1572,13 @@ install_node_deps() {\n         # Playwright's --with-deps only supports apt-based systems natively.\n         # For Arch/Manjaro we install the system libs via pacman first.\n         # Other systems must install Chromium dependencies manually.\n+        if [ \"$SKIP_BROWSER\" = true ]; then\n+            log_info \"Skipping Playwright/Chromium install (--skip-browser)\"\n+            log_info \"Browser tools will be unavailable until you run manually:\"\n+            log_info \"  cd $INSTALL_DIR && npx playwright install chromium\"\n+            log_info \"On apt-based systems, an admin also needs to run:\"\n+            log_info \"  sudo npx playwright install-deps chromium\"\n+        else\n         log_info \"Installing browser engine (Playwright Chromium)...\"\n         DETECTED_BROWSER_EXECUTABLE=\"$(find_system_browser 2>/dev/null || true)\"\n         if [ -n \"$DETECTED_BROWSER_EXECUTABLE\" ]; then","@@ -1574,12 +1587,30 @@ install_node_deps() {\n         else\n             case \"$DISTRO\" in\n                 ubuntu|debian|raspbian|pop|linuxmint|elementary|zorin|kali|parrot)\n-                    log_info \"Playwright may request sudo to install browser system dependencies (shared libraries).\"\n-                    log_info \"This is standard Playwright setup — Hermes itself does not require root access.\"\n-                    cd \"$INSTALL_DIR\" && run_browser_install_with_timeout 600 npx playwright install --with-deps chromium 2>/dev/null || {\n-                        log_warn \"Playwright browser installation failed — browser tools will not work.\"\n-                        log_warn \"Try running manually: cd $INSTALL_DIR && npx playwright install --with-deps chromium\"\n-                    }\n+                    # Use --with-deps only when sudo is available non-interactively\n+                    # (root, or a user with passwordless sudo). Non-sudo users\n+                    # — typical for systemd service accounts and unprivileged\n+                    # operator users — would otherwise get blocked on an\n+                    # interactive sudo prompt that they can't satisfy. Fall back\n+                    # to the browser-only install in that case, and print the\n+                    # exact command the admin needs to run separately.\n+                    if [ \"$(id -u)\" -eq 0 ] || (command -v sudo >/dev/null 2>&1 && sudo -n true 2>/dev/null); then\n+                        log_info \"Installing Playwright Chromium with system dependencies...\"\n+                        cd \"$INSTALL_DIR\" && run_browser_install_with_timeout 600 npx playwright install --with-deps chromium 2>/dev/null || {\n+                            log_warn \"Playwright browser installation failed — browser tools will not work.\"\n+                            log_warn \"Try running manually: cd $INSTALL_DIR && npx playwright install --with-deps chromium\"\n+                        }\n+                    else\n+                        log_warn \"No sudo available — skipping system-library install (--with-deps).\"\n+                        log_info \"Ask an administrator to run, one time, as root:\"\n+                        log_info \"  sudo npx playwright install-deps chromium\"\n+                        log_info \"  (from $INSTALL_DIR, after Node.js deps are installed)\"\n+                        log_info \"Installing Chromium binary into this user's Playwright cache...\"\n+                        cd \"$INSTALL_DIR\" && run_browser_install_with_timeout 600 npx playwright install chromium 2>/dev/null || {\n+                            log_warn \"Playwright browser installation failed — browser tools will not work.\"\n+                            log_warn \"Try running manually: cd $INSTALL_DIR && npx playwright install chromium\"\n+                        }\n+                    fi\n                     ;;\n                 arch|manjaro|cachyos|endeavouros|garuda)\n                     if command -v pacman &> /dev/null; then","@@ -1624,6 +1655,7 @@ install_node_deps() {\n                     ;;\n             esac\n         fi\n+        fi\n         log_success \"Browser engine setup complete\"\n     fi\n "]},{"file":"tests/test_install_sh_browser_install.py","hunks":["@@ -32,4 +32,29 @@ def test_playwright_installs_are_timeout_guarded() -> None:\n \n     assert \"run_browser_install_with_timeout()\" in text\n     assert \"run_browser_install_with_timeout 600 npx playwright install chromium\" in text\n+    # --with-deps is still invoked on apt-based systems, but only when sudo\n+    # is available non-interactively (root or passwordless sudo). Non-sudo\n+    # service users fall back to the browser-only install — see\n+    # install_node_deps() in install.sh.\n     assert \"run_browser_install_with_timeout 600 npx playwright install --with-deps chromium\" in text\n+\n+\n+def test_install_script_supports_skip_browser_flag() -> None:\n+    \"\"\"--skip-browser (and --no-playwright alias) skips the Playwright install.\"\"\"\n+    text = INSTALL_SH.read_text()\n+\n+    assert \"--skip-browser|--no-playwright)\" in text\n+    assert \"SKIP_BROWSER=true\" in text\n+    assert 'if [ \"$SKIP_BROWSER\" = true ]; then' in text\n+    assert \"--skip-browser Skip Playwright/Chromium install\" in text\n+\n+\n+def test_install_script_skips_with_deps_when_no_sudo() -> None:\n+    \"\"\"Non-sudo users on apt distros must not block on an interactive sudo prompt.\"\"\"\n+    text = INSTALL_SH.read_text()\n+\n+    # The apt branch must gate --with-deps behind a sudo capability check\n+    # (root or non-interactive sudo), otherwise the installer hangs for\n+    # service-user installs (systemd accounts, operator users, etc.).\n+    assert 'if [ \"$(id -u)\" -eq 0 ] || (command -v sudo >/dev/null 2>&1 && sudo -n true 2>/dev/null); then' in text\n+    assert \"sudo npx playwright install-deps chromium\" in text"]},{"file":"website/docs/getting-started/installation.md","hunks":["@@ -132,6 +132,43 @@ If you want to clone the repo and install from source — for contributing, runn\n \n ---\n \n+## Non-Sudo / System Service User Installs\n+\n+Running Hermes as a dedicated unprivileged user (e.g. a `hermes` systemd service account, or any user without `sudo` access) is supported. The only thing on the install path that genuinely needs root is Playwright's `--with-deps` step, which `apt`-installs shared libraries (`libnss3`, `libxkbcommon`, etc.) used by Chromium. The installer detects whether sudo is available and gracefully degrades when it isn't — it will install the Chromium binary into the service user's own Playwright cache and print the exact command an administrator needs to run separately.\n+\n+**Recommended split (Debian/Ubuntu):**\n+\n+1. **One time, as an admin user with sudo**, install the system libraries Chromium needs:\n+   ```bash\n+   sudo npx playwright install-deps chromium\n+   ```\n+   (You can run this from anywhere — `npx` will fetch Playwright on the fly.)\n+\n+2. **As the unprivileged service user**, run the regular installer. It will detect the missing sudo, skip `--with-deps`, and install Chromium into the user's local Playwright cache:\n+   ```bash\n+   curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash\n+   ```\n+\n+   If you want to skip the Playwright step entirely — for example because you're running headless and don't need browser automation — pass `--skip-browser`:\n+   ```bash\n+   curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash -s -- --skip-browser\n+   ```\n+\n+3. **Make `hermes` available to the service user's shells.** The installer writes the launcher to `~/.local/bin/hermes`. System service accounts often have a minimal PATH that doesn't include `~/.local/bin`. Either add it to the user's environment, or symlink the launcher into a system location:\n+   ```bash\n+   # Option A — add to the service user's profile\n+   echo 'export PATH=\"$HOME/.local/bin:$PATH\"' >> ~/.bashrc\n+\n+   # Option B — symlink system-wide (run as an admin)\n+   sudo ln -s /home/hermes/.hermes/hermes-agent/venv/bin/hermes /usr/local/bin/hermes\n+   ```\n+\n+4. **Verify:** `hermes doctor` should now run cleanly. If you get `ModuleNotFoundError: No module named 'dotenv'`, you're invoking the repo source `hermes` file (`~/.hermes/hermes-agent/hermes`) with system Python instead of the venv launcher (`~/.hermes/hermes-agent/venv/bin/hermes`) — fix step 3.\n+\n+The same pattern works on Arch (the installer uses pacman with the same sudo-detection logic), Fedora/RHEL, and openSUSE — those distros don't support `--with-deps` at all, so an administrator always installs the system libraries separately. The relevant `dnf`/`zypper` commands are printed by the installer.\n+\n+---\n+\n ## Troubleshooting\n \n | Problem | Solution |\n"]}]}],"trust":{"default_tier":"verified","includes_suggested":false}}