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.sh is a Bash script that detects the current platform and CPU architecture, bootstraps the isolated portable environment, and either opens the interactive ANSI terminal menu or passes arguments directly to the hermes CLI. It requires no pre-installed Python, Node.js, or any other dependency on the host machine — all runtimes are downloaded on first run and stored inside the portable folder.
Usage
chmod +x launch.sh
./launch.sh
./launch.sh [hermes] <command> [args...]
hermes prefix is accepted for ergonomics and is stripped before arguments are forwarded — ./launch.sh hermes setup and ./launch.sh setup are identical.
macOS Finder double-click: Rename launch.sh to launch.command. macOS recognizes the .command extension and opens the file in Terminal automatically when double-clicked, with no need to use the command line first.
Commands
| Command | What it does |
|---|
./launch.sh | Start Hermes TUI (interactive chat interface) |
./launch.sh setup | Run the setup wizard |
./launch.sh gateway | Start the messaging gateway (Telegram, etc.) |
./launch.sh hermes doctor | Check the environment for issues |
./launch.sh hermes status | Show current Hermes status |
./launch.sh hermes config | View the current configuration |
./launch.sh hermes update | Update Hermes to the latest version |
uname to identify the operating system and CPU architecture, then selects the matching runtime directory:
OS_RAW="$(uname -s)" # e.g. Linux, Darwin
ARCH_RAW="$(uname -m)" # e.g. x86_64, aarch64, arm64
uname -s output | Mapped PLATFORM |
|---|
Linux* | linux |
Darwin* | macos |
CYGWIN*, MINGW*, MSYS* | windows |
uname -m output | Mapped ARCH |
|---|
x86_64, amd64 | x64 |
aarch64, arm64 | arm64 |
.cache/runtimes/<platform>-<arch>/
.cache/runtimes/macos-arm64/ and an x86-64 Linux machine resolves to .cache/runtimes/linux-x64/.
If launch.sh detects an unsupported OS or architecture combination, it prints an error and exits immediately. Supported combinations are: linux-x64, linux-arm64, macos-x64, and macos-arm64.
Virtual Environment Handling
The Python virtual environment (venv) is intentionally stored on the local filesystem rather than inside the portable folder on the drive. This is necessary because exFAT-formatted USB drives — the most common cross-platform format — do not support the hard links that Python’s venv module requires.
Where the venv lives
| Platform | Default local base | Venv path |
|---|
| macOS | $TMPDIR (falls back to /tmp) | $TMPDIR/hermes-portable-venv-<id> |
| Linux | /tmp | /tmp/hermes-portable-venv-<id> |
<id> is an 8-character hash derived from the runtime directory path, so two separate portable drives on the same machine always get distinct venv directories and never collide.
The resolved venv path is written to .cache/runtimes/<platform>-<arch>/venv.path so subsequent launches can find it without recomputing the hash.
Automatic rebuild after reboot
/tmp is typically cleared on reboot (and $TMPDIR on macOS may be cleared as well). The launcher detects this by checking for $VIRTUAL_ENV/bin/python:
if [ ! -x "$VIRTUAL_ENV/bin/python" ]; then
# Rebuild venv from cached packages on the drive
fi
uv and the package cache that was saved on the drive during initial setup. This rebuild is fast — typically a few seconds — because no new downloads are required. The launcher prints an informational message so you know what is happening:
[INFO] Local venv not found (temp was likely cleared). Rebuilding ...
This is fast because packages are cached on the drive.
The automatic venv rebuild means you can reboot the host computer freely. The next time you run ./launch.sh, the environment is transparently restored from the drive’s cached packages without any manual intervention.
Environment Variables
The launcher exports the following variables into the session. No changes are made to the host’s shell profile, .bashrc, .zshrc, or any system-level configuration.
| Variable | Value | Purpose |
|---|
PORTABLE_ROOT | Absolute path to the directory containing launch.sh | Anchor for all other paths |
HERMES_HOME | $PORTABLE_ROOT/data | Overrides the default Hermes data directory so all configs and sessions stay on the drive |
VIRTUAL_ENV | Path to the local venv (read from venv.path or auto-detected) | Points Python tools to the correct isolated environment |
PATH | $VIRTUAL_ENV/bin:$RUNTIME_DIR/python/bin:$RUNTIME_DIR/node/bin:$RUNTIME_DIR/uv:$RUNTIME_DIR/bin:… | Prepends portable runtime binaries so they take precedence over any host-installed tools |
PYTHONNOUSERSITE | 1 | Prevents 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_CONFIG | 1 | Prevents uv from reading any config file on the host machine |
UV_PYTHON | $RUNTIME_DIR/python/bin/python3 | Pins uv to the portable Python binary |
PLAYWRIGHT_BROWSERS_PATH | $RUNTIME_DIR/playwright | Redirects Playwright browser binaries to the local cache |
NODE_PATH | $RUNTIME_DIR/node/lib/node_modules | Points Node.js module resolution to the portable node_modules directory |
NPM_CONFIG_PREFIX | $RUNTIME_DIR/node | Redirects npm global installs to the portable runtime directory |
HOME | $PORTABLE_ROOT/.cache/unix-home | Prevents Node.js, npm, and other tools from writing into the host user’s home directory |
Redirecting HOME means any tool running inside the session that reads ~ or $HOME will see the portable folder’s .cache/unix-home directory instead of your actual home directory. This is intentional — it ensures zero host pollution — but be aware that shell history, SSH keys, and other home-directory resources are not accessible from within the session.
Behavior Notes
First-run setup check
Before taking any launch action, the script checks for .cache/runtimes/<platform>-<arch>/ready.flag. If absent, it invokes:
bash "$PORTABLE_ROOT/scripts/setup-unix.sh" "$PORTABLE_ROOT"
hermes prefix stripping
When the first argument is hermes (or HERMES), it is shifted off before the remaining arguments are forwarded:
if [ "$1" = "hermes" ] || [ "$1" = "HERMES" ]; then
shift
fi
./launch.sh hermes doctor
./launch.sh doctor
| Scenario | Behavior |
|---|
| No arguments | The ANSI terminal menu is displayed with live setup, provider, gateway, and version status. The user selects options with number keys. |
| Arguments present | hermes is called directly with those arguments and the script exits when it returns. The menu is never shown. |
- [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 running state
- [4] Advanced Options — sub-menu with Doctor, View Logs, Edit Config, Restart Gateway, and Update Hermes
- [5] Exit