Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/techjarves/Hermes-USB-Portable/llms.txt

Use this file to discover all available pages before exploring further.

This page covers the most common setup and runtime errors encountered with Hermes USB Portable, along with their causes and step-by-step fixes. If you are seeing an issue not listed here, run the built-in diagnostics with hermes doctor or check the launcher’s Advanced Options → Run Doctor.
Cause: The first-run setup downloads approximately 600 MB of runtime files (Python, Node.js, uv, and the Hermes Agent source). A dropped or restricted internet connection will cause it to fail or hang.Corporate and school networks commonly block the CDN endpoints used by Node.js and GitHub Releases, which are required during setup.Fix:
  1. Verify your internet connection is active and stable.
  2. If you are on a corporate or school network, try connecting through a VPN to bypass firewall restrictions on Node.js CDNs and GitHub.
  3. Delete the .cache/ folder to remove any partially downloaded files:
rm -rf .cache/
./launch.sh
The launcher will detect the missing ready.flag and restart setup from scratch.
Do not delete the data/ folder — it contains your API keys, sessions, and memories. Only .cache/ needs to be removed to trigger a clean reinstall of the runtimes.
Cause: macOS Gatekeeper blocks execution of files downloaded from the internet that lack an Apple developer signature. launch.sh (and launch.command) will trigger this warning on first open.Fix — Option 1: Right-click to open
  1. In Finder, right-click launch.sh (or launch.command).
  2. Select Open With → Terminal.
  3. Click Open in the security dialog that appears.
This grants a one-time exception for the file without disabling Gatekeeper globally.Fix — Option 2: Strip the quarantine flagOpen Terminal and run the following command, replacing the path with the actual location of your portable folder:
xattr -dr com.apple.quarantine /path/to/hermes-portable
This removes the quarantine extended attribute from the entire folder, allowing all scripts and binaries inside it to run without Gatekeeper prompts.
For double-click convenience in Finder, rename launch.sh to launch.command. macOS recognises .command files and opens them directly in Terminal — you still need to grant the initial Gatekeeper exception the first time.
Cause: This is a false positive. Windows SmartScreen flags PowerShell scripts that download files from remote sources (the Hermes setup script pulls from GitHub Releases and the Node.js CDN), even when the scripts themselves are benign.Fix:
  1. When the SmartScreen dialog appears, click “More info”.
  2. Click “Run anyway” to allow execution.
The setup scripts are fully open-source and human-readable. You can inspect them yourself in the scripts/ directory before running — scripts/setup-windows.ps1 for Windows and scripts/setup-unix.sh for macOS/Linux.
Do not disable Windows Defender or SmartScreen globally. The one-time “Run anyway” exception is sufficient and does not weaken your system’s security posture.
Cause: Older USB 2.0 drives have significantly slow read/write speeds (typically 10–25 MB/s). Python’s module import system performs many small, sequential file reads at startup — this is severely bottlenecked by USB 2.0 I/O, making launch times feel sluggish and commands feel unresponsive.Fix:Upgrade to a faster storage medium. In order of preference:
Storage TypeTypical Read SpeedSuitability
USB 2.0 flash drive10–25 MB/s⚠️ Slow — not recommended
USB 3.0 flash drive80–150 MB/s✅ Good
USB 3.1 / 3.2 flash drive150–400 MB/s✅ Better
External SSD (USB 3.x)400–1000 MB/s✅ Best
Look for USB 3.0 or higher (blue port on the host) and ensure the drive is also USB 3.0-rated on the device side.
Cause: Some operating system sandboxing policies prevent Chromium and other browsers from launching when their binaries are located inside an external or removable drive directory. This affects Hermes’s web browsing and screenshot tools, which are powered by Playwright.Fix:Copy the entire hermes-portable folder from the USB drive to your local SSD, then run the launcher from that location:
cp -r /Volumes/MyUSB/hermes-portable ~/hermes-portable
cd ~/hermes-portable
./launch.sh
Running from the local SSD also improves overall performance significantly. Your data/ folder and all personal files will be in the copied location — remember to sync changes back to the USB drive if portability is important.
Cause: The launcher stores the gateway’s process ID in data/gateway.pid. If the gateway process was killed unexpectedly (e.g. system shutdown, kill, or a crash), the PID file remains on disk but the process no longer exists. The launcher detects this mismatch and shows “Stopped (stale lock)”.Fix — Option 1: Restart the gateway via the launcherSelect [3] Start Gateway from the main menu (or [4] Advanced Options → [4] Restart Gateway). The launcher will overwrite the stale lock file automatically when it starts a new gateway process.Fix — Option 2: Delete the PID file manually
rm data/gateway.pid
After deleting the file, the launcher will show “Stopped” (clean state) and you can start the gateway normally.
Cause: On Unix systems (macOS and Linux), the Python virtual environment (venv) is intentionally created in a temporary local directory (/tmp on Linux, or $TMPDIR on macOS) rather than on the USB drive itself. This avoids filesystem limitations of exFAT-formatted drives, which do not support the hard links that Python’s venv module requires.Because /tmp is cleared on reboot, the venv disappears after a system restart.Fix: No manual action required. The launcher automatically detects that the venv is missing and rebuilds it from packages cached on the drive:
[INFO] Local venv not found (temp was likely cleared). Rebuilding ...
       This is fast because packages are cached on the drive.
[OK]   Venv rebuilt.
This rebuild is fast because the Python packages do not need to be re-downloaded — they are read from the local .cache/ on the drive. The launcher then resumes normally.
This behaviour is by design. The drive cache ensures the rebuild works even without an internet connection after first setup.
Cause: Installing Hermes’s Python dependencies involves downloading and compiling several packages. On a slow internet connection or a USB 2.0 drive, this step can legitimately take 3–10 minutes and may appear frozen even when progress is occurring in the background.Fix:
  1. Wait. Allow at least 15 minutes before assuming the setup has truly frozen. The terminal may appear idle while packages are being fetched and installed.
  2. If setup is still stuck after 15 minutes, cancel it (press Ctrl+C), delete the .cache/ folder, and relaunch:
# Cancel with Ctrl+C, then:
rm -rf .cache/
./launch.sh
Do not interrupt setup during the dependency installation step unless you have waited the full 15 minutes. A partial install may leave corrupted package files in .cache/ — always delete the entire .cache/ folder before retrying.
Running from a USB 3.0 drive or external SSD dramatically reduces installation time by eliminating the I/O bottleneck inherent to USB 2.0 flash drives.

Build docs developers (and LLMs) love

Get started for freeTalk to us