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 is designed to be self-contained, private, and cross-platform with zero host dependencies. The questions below cover the most common points users ask when getting started or moving their drive across systems.
No. Hermes Portable is fully self-contained. On first run, the launcher automatically downloads and installs Python 3.11, Node.js 22, and all required dependencies directly into the portable folder — nothing is written to the host operating system, registry, or user profile.
The first-run setup downloads approximately 600 MB of runtime files. A stable internet connection is required for this initial step only.
Yes. The launcher detects the operating system and CPU architecture at startup and stores each platform’s runtime in its own isolated directory:
.cache/runtimes/
├── windows-x64/
├── macos-arm64/
├── macos-x64/
├── linux-x64/
└── linux-arm64/
Each platform you use performs its own first-run setup into its respective folder. Keep in mind that storage usage multiplies per platform — plan for 4–6 GB for two platforms, or 8 GB+ if you intend to use Windows, macOS, and Linux from the same drive.
Your personal data in data/ — sessions, memories, API keys, and skills — is shared across all platforms automatically, since it lives in a single location on the drive.
Everything moves with the drive. All personal data is stored exclusively inside the data/ folder:
WhatWhere
Chat historiesdata/sessions/
Persistent memorydata/memories/
Learned skillsdata/skills/
API keys & credentialsdata/.env
LLM configurationdata/config.yaml
Custom system promptdata/SOUL.md
Plug the drive into any supported machine, run the launcher, and your full agent context is immediately available.
Back up your data/ folder regularly. It contains your API keys, conversation history, and all agent memory. Consider encrypting the drive using BitLocker (Windows), FileVault (macOS), or VeraCrypt for cross-platform encryption.
Yes. Any API key that works with Hermes Agent works with Hermes Portable. OpenRouter is a particularly good option for free-tier usage as it provides access to multiple models through a single key.To configure your keys, open data/.env in any text editor and add your credentials:
# Add the keys for the providers you wish to use:
OPENROUTER_API_KEY=sk-or-v1-xxxxxxxxxxxxxxxx
OPENAI_API_KEY=sk-proj-xxxxxxxxxxxxxxxx
ANTHROPIC_API_KEY=sk-ant-xxxxxxxxxxxxxxxx
Alternatively, select [2] Setup / Reconfigure Hermes from the launcher menu to configure providers interactively through the setup wizard.
Yes. Linux ARM64 is a fully supported platform. The launcher detects aarch64 / arm64 architecture automatically and downloads the appropriate portable Python and Node.js binaries into .cache/runtimes/linux-arm64/.This covers Raspberry Pi 4/5, ARM-based cloud VMs (e.g. AWS Graviton, Oracle Ampere), and other ARM64 single-board computers running Ubuntu, Debian, Fedora, or similar distributions.
Create or edit the file data/SOUL.md inside your portable folder. Hermes loads this file as the system prompt at the start of every conversation.
hermes-portable/
└── data/
    └── SOUL.md   ← create or edit this file
Write any markdown-formatted instructions you want Hermes to follow persistently — persona, tone, rules, or domain-specific context. The file is plain text and can be edited in any text editor while Hermes is not running.
The gateway is an optional background service that enables Hermes to receive and respond to messages from external platforms such as Telegram and WhatsApp. It runs as a separate process in the background.You do not need the gateway for regular chat use. If you only use Hermes through the terminal UI (option [1] Start Hermes Chat), you can ignore it entirely.To start or stop the gateway, use option [3] from the launcher’s main menu, or use the command line directly:
./launch.sh gateway
./launch.sh hermes gateway stop
./launch.sh hermes gateway restart
Yes, provided you are using a local Ollama model. Once the first-run setup has completed:
  • All Python and Node.js runtimes are cached locally in .cache/runtimes/
  • The Hermes Agent source code is stored in src/hermes-agent/
  • No external downloads are required for subsequent launches
To use a local Ollama instance, start Ollama on the host machine, pull a model (e.g. ollama pull qwen3.6), then configure Hermes via [2] Setup / Reconfigure and point it to http://127.0.0.1:11434/v1 with a blank API key.
If you are using a cloud-based API provider (OpenAI, Anthropic, OpenRouter), an internet connection is still required to make inference calls — only the runtimes and source code are local.
Your API keys are stored in data/.env inside the portable folder — and only there. They are never written to the host machine’s environment, registry, or home directory.
# data/.env — stays on your drive, never touches the host
OPENROUTER_API_KEY=sk-or-v1-xxxxxxxxxxxxxxxx
OPENAI_API_KEY=sk-proj-xxxxxxxxxxxxxxxx
ANTHROPIC_API_KEY=sk-ant-xxxxxxxxxxxxxxxx
Because data/.env contains raw API keys, anyone with physical access to your drive can read them. Encrypt your USB drive or external SSD using BitLocker, FileVault, or VeraCrypt, and avoid storing large API balances or production keys on drives you carry daily.
Run the built-in doctor diagnostic tool. It checks your setup, environment, and configuration for common issues:
./launch.sh hermes doctor
You can also access it through the launcher menu: select [4] Advanced Options, then [1] Run Doctor.

Build docs developers (and LLMs) love

Get started for freeTalk to us