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.

launch.bat is a Windows Batch script that bootstraps the entire portable environment and launches the Hermes terminal menu — or, when arguments are provided, passes them directly to the hermes CLI without opening the menu. Double-clicking it in Explorer is all that is required on first run; the script detects whether the runtime is ready and, if not, invokes the PowerShell setup script automatically before continuing.

​
Usage

launch.bat
launch.bat [hermes] <command> [args...]
The optional hermes prefix is accepted purely for ergonomics — launch.bat hermes setup and launch.bat setup are identical.
On first run, the launcher downloads approximately 600 MB of runtime files (Python, Node.js, uv, Playwright, and the Hermes source tree) into .cache\runtimes\windows-x64\. Subsequent launches skip this step entirely.

​
Commands

CommandWhat it does
launch.batStart Hermes TUI (interactive chat interface)
launch.bat hermesSame as above
launch.bat setupRun the setup wizard
launch.bat hermes setupSame as above
launch.bat gatewayStart the messaging gateway (Telegram, etc.)
launch.bat hermes gatewaySame as above
launch.bat hermes gateway restartRestart the running gateway
launch.bat hermes gateway stopStop the running gateway
launch.bat hermes doctorCheck the environment for issues
launch.bat hermes statusShow current Hermes status
launch.bat hermes configView the current configuration
launch.bat hermes config editOpen the config file in the default editor
launch.bat hermes chatStart chat mode
launch.bat hermes updateUpdate Hermes to the latest version

​
Environment Variables

The launcher sets the following environment variables in the process scope of the launched session. Nothing is written to the Windows registry or the user’s system environment — all changes are local to the running process.
VariableValuePurpose
PORTABLE_ROOTAbsolute path to the folder containing launch.batAnchor for all other paths
HERMES_HOME%PORTABLE_ROOT%\dataOverrides the default Hermes data directory so all configs and sessions stay on the drive
CACHE_DIR%PORTABLE_ROOT%\.cacheRoot of all cached runtime files
RUNTIME_DIR%PORTABLE_ROOT%\.cache\runtimes\windows-x64Platform-specific runtime directory for Python, Node.js, uv, and Playwright
VIRTUAL_ENV%RUNTIME_DIR%\venvPoints to the portable Python virtual environment
PATH%VIRTUAL_ENV%\Scripts;%RUNTIME_DIR%\python;%RUNTIME_DIR%\python\Scripts;%RUNTIME_DIR%\node;%RUNTIME_DIR%\uv;%RUNTIME_DIR%\bin;…Prepends portable runtime binaries so they take precedence over any host-installed tools
PYTHONNOUSERSITE1Prevents Python from loading packages from the host user’s site-packages
PYTHONHOME(cleared)Cleared to prevent host Python installations from interfering
PYTHONPATH(cleared)Cleared to prevent host Python paths from leaking into the isolated environment
UV_NO_CONFIG1Prevents uv from reading any config file on the host machine
UV_PYTHON%RUNTIME_DIR%\python\python.exePins uv to the portable Python binary
PLAYWRIGHT_BROWSERS_PATH%RUNTIME_DIR%\playwrightRedirects Playwright browser binaries to the local cache instead of the host AppData
NODE_PATH%RUNTIME_DIR%\node\node_modulesPoints Node.js module resolution to the portable node_modules directory
NPM_CONFIG_PREFIX%RUNTIME_DIR%\nodeRedirects npm global installs to the portable runtime directory
APPDATA%PORTABLE_ROOT%\.cache\windows-appdataPrevents Node.js and other tools from writing into the host user’s AppData
LOCALAPPDATA%PORTABLE_ROOT%\.cache\windows-localappdataSame isolation applied to LocalAppData
Because APPDATA and LOCALAPPDATA are redirected, any tool running inside this session that would normally persist data to the Windows user profile writes into the portable folder instead, keeping the host machine completely clean.

​
Behavior Notes

​
First-run setup check

Before any launch action, the script tests for the presence of .cache\runtimes\windows-x64\ready.flag. If that file does not exist, it immediately calls: 
powershell -ExecutionPolicy Bypass -File "%PORTABLE_ROOT%\scripts\setup-windows.ps1" -Root "%PORTABLE_ROOT%"
If the setup script exits with an error, the launcher prints a message and halts with exit /b 1. The ready.flag is only written at the very end of a successful setup, so an interrupted download will always re-trigger setup on the next launch.

​
pyvenv.cfg portability fix

On every launch — not just the first — the launcher rewrites %VIRTUAL_ENV%\pyvenv.cfg with the current absolute path to the portable Python interpreter: 
echo home = %RUNTIME_DIR%\python          > "%VIRTUAL_ENV%\pyvenv.cfg"
echo include-system-site-packages = false >> "%VIRTUAL_ENV%\pyvenv.cfg"
echo version = <detected>                 >> "%VIRTUAL_ENV%\pyvenv.cfg"
This is necessary because pyvenv.cfg contains a hard-coded home = path. When the drive is moved to a different machine or mounted on a different drive letter, the path changes and Python would fail to activate the venv correctly. Rewriting the file on every launch ensures the venv always points to the correct location regardless of where the drive is plugged in.

​
hermes prefix stripping

When the first argument equals hermes (case-insensitive), it is stripped before the remaining arguments are forwarded. This means the two forms below are exactly equivalent: 
launch.bat hermes setup
launch.bat setup

​
Direct execution vs. interactive menu

ScenarioBehavior
No argumentsThe ANSI terminal menu is displayed, showing setup status, provider, model, gateway state, and version. The user navigates with number keys.
Arguments presentHermes runs in the foreground with those arguments and exits when done. The menu is never shown.
If src\hermes-agent is missing (for example, after a partial setup or a manual deletion), the launcher will print an error and exit rather than attempting to run. Delete .cache and re-launch to trigger a clean setup.

​
Interactive menu overview

When launched with no arguments, the launcher renders a color dashboard and offers:
  • [1] Start Hermes Chat — opens the TUI chat interface
  • [2] Setup / Reconfigure Hermes — runs hermes setup
  • [3] Start / Stop Gateway — toggles the messaging gateway; label reflects live state
  • [4] Advanced Options — sub-menu with Doctor, View Logs, Edit Config, Restart Gateway, and Update Hermes
  • [5] Exit

Build docs developers (and LLMs) love

Get started for freeTalk to us