Run a fully self-contained, self-improving AI agent from a single folder or USB drive.
No global installation. Zero host pollution. All conversations, configs, memories, and skills stay inside your folder.

📺 Watch the Setup & Demo Video: Click the image above to watch the step-by-step walkthrough.

• Zero Host Dependencies: No pre-installed Python, Node.js, or package managers required on the computer. All runtimes are downloaded locally.
• 100% Portable: Copy the entire directory to a USB flash drive or external SSD. Run it on any Windows, macOS, or Linux computer instantly.
• True Privacy & Isolation: Your API keys (data/.env), conversations (data/sessions/), persistent memory, and custom skills are kept strictly within the portable folder.
• Interactive Console Launcher: Includes a beautiful terminal UI dashboard with state-tracking for setup status, LLM providers, and background gateways.
• Full Hermes Capabilities: Retains all features of Nous Research's Hermes Agent, including memory storage and reusable skill generation.

Get Hermes running in seconds depending on your operating system:

Simply double-click the launch.bat file in this folder.

Note: On first run, it will launch a PowerShell window to download dependencies and configure your runtime environment.

Open your terminal in this directory and execute:

chmod +x launch.sh
./launch.sh

💡 macOS Double-Click Shortcut: If you want to double-click in Finder to launch, rename launch.sh to launch.command. macOS recognizes .command files and opens them in Terminal automatically.

Hermes Portable solves the host-dependency issue by establishing a sandboxed runtime context pointing inwards.

graph TD
    A[User triggers launch script] --> B{Runtimes setup?}
    B -- No / First Run --> C[Download Portable Python 3.11 & Node.js 22]
    C --> D[Clone Hermes Agent Source to src/]
    D --> E[Create isolated virtual env using uv]
    E --> F[Install Python & Node packages locally]
    F --> G[Generate ready.flag]
    B -- Yes / Ready --> H[Configure environment variables]
    G --> H
    H --> I[Set HERMES_HOME = data/]
    I --> J[Prepend portable bin/ paths to Env PATH]
    J --> K[Launch Terminal Dashboard Menu]
    K --> L[Start Chat / Background Gateway]

1. Custom Data Directory: The launcher overrides HERMES_HOME to the local data/ folder, forcing Hermes to write configuration and data locally rather than in ~/.hermes/.
2. Local Path Sandboxing: The scripts download self-contained Python and Node.js binaries into .cache/runtimes/ and prepend them directly to the active process PATH.
3. No Registry/Host Pollution: System configurations, environment variables, or packages on the host machine are left untouched.

A clean, modular layout where runtime caches are separated from your personal configurations.

hermes-portable/
├── launch.bat                 # Windows interactive launcher script
├── launch.sh                  # macOS & Linux interactive launcher script
├── scripts/
│   ├── setup-windows.ps1      # Windows first-run configuration script
│   └── setup-unix.sh          # Unix (macOS/Linux) first-run configuration script
├── data/                      # ⚠️ [BACKUP THIS] All your private files
│   ├── config.yaml            # Hermes LLM provider configurations
│   ├── .env                   # API Keys and active credentials
│   ├── sessions/              # Chronological chat histories
│   ├── memories/              # Persistent memory databases
│   └── skills/                # Learned custom skills
├── src/                       # Downloaded Hermes Agent source code
│   └── hermes-agent/
└── .cache/                    # Sandbox cache & binaries
    └── runtimes/              # Platform-specific portable interpreters
        ├── windows-x64/
        ├── macos-arm64/
        ├── macos-x64/
        ├── linux-x64/
        └── linux-arm64/

To configure your language models, open and edit the environment variables in data/.env:

# 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, you can select option [2] (Setup / Reconfigure) in the Launcher Terminal Menu to configure model providers interactively.

Hermes Portable can use an Ollama server that is already running on the same computer. Start Ollama first, then pull a model:

ollama pull qwen3.6

Launch Hermes Portable and choose [2] Setup / Reconfigure Hermes. In the Hermes setup wizard:

1. Choose Quick setup.
2. Select More providers.
3. Select Custom endpoint (enter URL manually).
4. Enter the local OpenAI-compatible Ollama endpoint:

http://127.0.0.1:11434/v1

5. Leave the API key blank when prompted.
6. Select the detected Ollama model and leave context length blank to auto-detect it.

For a remote Ollama host, use the same /v1 endpoint format, for example http://192.168.1.20:11434/v1. Make sure the Ollama host is reachable from the computer running Hermes Portable.

The current Windows x64 full first-run setup was measured at about 1.5 GB total after setup completed.

Recommended USB / external drive free space:

ℹ️ Each operating system and CPU architecture gets its own .cache/runtimes/<platform>-<arch>/ folder, so using the same USB drive across Windows, macOS, and Linux will increase storage usage.

Keep your agent up-to-date with the latest improvements from Nous Research:

• Via Chat Command: Within an active Hermes conversation, type:

  /hermes update
  

• Via Launcher: Navigate to [4] Advanced Options -> [5] Update Hermes in the Launcher terminal dashboard.
• Manual Rebuild: Delete .cache/runtimes/<your-platform> and the src/hermes-agent directory, then re-run the launcher to fetch the latest code from scratch.

• Hermes Agent — Powerful Agentic core created by Nous Research.
• python-build-standalone — Portable Python interpreter compilation.
• uv — Blazing fast package installer and resolver.