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.

Hermes USB Portable runs natively on Windows, macOS, and Linux across both x86_64 and ARM64 CPU architectures. Because each platform requires its own Python, Node.js, and toolchain binaries, the launcher automatically detects the current operating system and architecture at startup, then downloads and caches the correct runtimes under a per-platform subfolder inside .cache/runtimes/. This means a single portable folder can serve multiple operating systems without any manual configuration.

​
Support Matrix

Operating SystemCPU ArchitectureStatusNotes
Windows 10 / 11x86_64✅ SupportedDefault PowerShell ExecutionPolicy bypassed for script
macOS 13+Apple Silicon (ARM64)✅ SupportedNative M1/M2/M3 execution
macOS 13+Intel (x86_64)✅ SupportedLegacy Intel Mac support
Linux (Ubuntu/Arch/Debian)x86_64✅ SupportedFully self-contained
Linux (Fedora/CentOS)ARM64✅ SupportedSupports SBCs and ARM servers

​
Multi-Platform USB Usage

When you use the same portable folder or USB drive across multiple operating systems, each platform downloads its own runtime binaries into a separate subdirectory: 
.cache/
└── runtimes/
    ├── windows-x64/      ← populated the first time you run on Windows
    ├── macos-arm64/      ← populated the first time you run on an Apple Silicon Mac
    ├── macos-x64/        ← populated the first time you run on an Intel Mac
    ├── linux-x64/        ← populated the first time you run on Linux x86_64
    └── linux-arm64/      ← populated the first time you run on Linux ARM64
Each directory is completely independent. Your personal data (data/) is shared across all platforms — your conversations, memories, API keys, and skills are always available regardless of which computer you plug into.
Because every platform gets its own runtime cache, using the same USB drive across Windows, macOS, and Linux will multiply your storage usage. Each platform cache is approximately 800 MB–1.5 GB.

​
Storage Requirements

Use CaseRecommended Free Space
One platform only2 GB minimum, 4 GB recommended
Windows + one Unix platform4–6 GB recommended
Windows + macOS + Linux runtimes8 GB+ recommended
Heavy long-term use with many sessions/backups16–32 GB recommended

​
Component Breakdown

ComponentApproximate SizeNotes
Launchers & scripts< 1 MBMetadata and setup automation
Windows x64 runtime~800 MBPython, Node.js, uv, Git, ripgrep, venv, and downloaded archives
Playwright / local app cache~400–500 MBChromium browser cache used by Hermes web tools
Hermes source code~100 MBDownloaded Hermes Agent source tree
User data~10 MB → 2 GB+Grows as memory, logs, sessions, skills, and backups accumulate

​
Platform-Specific Notes

PowerShell ExecutionPolicylaunch.bat invokes the setup script with the -ExecutionPolicy Bypass flag so PowerShell can run the setup-windows.ps1 file without requiring any permanent system policy change:
powershell -ExecutionPolicy Bypass -File "%PORTABLE_ROOT%\scripts\setup-windows.ps1" -Root "%PORTABLE_ROOT%"
This flag applies only to that single PowerShell session and does not modify your system’s global execution policy.Windows Defender / SmartScreen false positiveWindows SmartScreen may flag launch.bat or setup-windows.ps1 because they download files from remote sources (GitHub and Node.js servers) at first run. This is a false positive.
  • Click More info on the SmartScreen dialog, then click Run anyway.
  • All scripts are fully open-source and human-readable inside the scripts/ directory.
Developer verification promptWhen you first run launch.sh (or launch.command) on macOS, Gatekeeper may display: “cannot be opened because the developer cannot be verified.”To work around this:
  • Right-click the file, choose Open With → Terminal, then click Open in the dialog.
  • Or open Terminal and strip the quarantine attribute from the entire portable folder:
xattr -dr com.apple.quarantine /path/to/hermes-portable
The setup script (setup-unix.sh) also runs this command automatically on all downloaded runtime binaries during first-run setup.Renaming to .command for Finder double-clickmacOS does not execute .sh files by double-clicking in Finder. To enable double-click launching, rename the file:
mv launch.sh launch.command
macOS recognizes .command files and opens them in Terminal automatically.
exFAT drive limitationsPython virtual environments require hardlinks, which the exFAT filesystem does not support. If your portable folder lives on an exFAT-formatted USB drive, the launcher automatically creates the virtual environment in /tmp instead:
# From launch.sh — venv is placed on local filesystem to avoid exFAT hardlink issues
LOCAL_BASE="/tmp"
DRIVE_ID="$(portable_id "$RUNTIME_DIR")"
VIRTUAL_ENV="${LOCAL_BASE}/hermes-portable-venv-${DRIVE_ID}"
A unique ID derived from the runtime directory path is used so multiple Hermes drives can coexist on the same machine without conflict.Venv rebuild after rebootBecause /tmp is typically cleared on reboot, the venv stored there will be missing after a system restart. The launcher detects this automatically and rebuilds the venv from the cached packages on the drive. This rebuild is fast (usually under a minute) because all package archives remain cached in .cache/runtimes/.Playwright browser sandboxingSome Linux distributions restrict Chromium from starting inside external or removable directories. If Playwright or web-tool features fail, copy the hermes-portable folder to a local SSD path and run from there.

​
Architecture Detection

The launcher automatically determines the correct runtime directory to use at startup without any user input. On macOS and Linux, launch.sh calls uname -s and uname -m to identify the operating system and CPU architecture: 
OS_RAW="$(uname -s)"
ARCH_RAW="$(uname -m)"

case "$OS_RAW" in
    Linux*)     PLATFORM="linux" ;;
    Darwin*)    PLATFORM="macos" ;;
    CYGWIN*|MINGW*|MSYS*) PLATFORM="windows" ;;
esac

case "$ARCH_RAW" in
    x86_64|amd64) ARCH="x64" ;;
    aarch64|arm64) ARCH="arm64" ;;
esac

RUNTIME_DIR="$CACHE_DIR/runtimes/${PLATFORM}-${ARCH}"
On Windows, launch.bat hard-codes the runtime directory to windows-x64 since the batch launcher only runs on Windows x86_64 hosts: 
set "RUNTIME_DIR=%CACHE_DIR%\runtimes\windows-x64"
The resolved RUNTIME_DIR path is then used for all subsequent environment variable setup, ensuring the correct Python, Node.js, and uv binaries are loaded into PATH for that session.

Build docs developers (and LLMs) love

Get started for freeTalk to us