aivrar/portable-hermes-agent

Portable Hermes Agent

Portable AI agent desktop for Windows — 100 tools, GUI, local models via LM Studio, TTS, Music, ComfyUI, workflows, tool maker. No install. No Docker. No admin rights.

Built on NousResearch/hermes-agent (MIT License) with extensive customization for non-technical users.

Features

Desktop GUI

• Dark-themed Tkinter interface with chat, sidebar, and session management
• Image attachment with thumbnails (vision model support)
• Guided mode — works even without an AI model connected
• API key setup wizard with individual service configuration
• Permissions panel with granular control over file, network, and system access

100 Tools Across 20+ Toolsets

Plus all built-in hermes-agent tools: web search, file operations, browser automation, code execution, delegation, memory, skills, messaging, Home Assistant, and more.

Extension Modules

Three portable AI generation servers from aivrar:

Each extension auto-installs on first use. No system dependencies.

Workflow Engine

Chain tool calls into automated pipelines with data flow, conditions, loops, parallel execution, error handling, and cron scheduling.

Dynamic Tool Maker

Create new tools at runtime — wrap any REST API or write custom Python handlers. Tools persist across sessions and reload automatically.

Guided Mode

No API key? No problem. The chat works offline using a built-in 1,054-line user guide. New users get step-by-step guidance to set up their first AI model.

Quick Start

1. Download

Download the latest portable-hermes-agent-v*.zip from Releases, then extract it to a normal folder.

Recommended:

C:\Users\YourName\Portable-Hermes-Agent

Avoid protected folders such as C:\Program Files.

2. Start

Double-click:

START.bat

On first launch, START.bat runs the portable setup automatically. It downloads embedded Python, dependencies, LM Studio SDK, and Node.js tools into this folder only. No admin rights are needed.

Manual setup:

install.bat

PowerShell users can run:

.\scripts\install.ps1

3. Launch Again

START.bat           :: easiest GUI launch
UPDATE.bat          :: safest one-click update
hermes_gui.bat      :: GUI mode
hermes.bat          :: CLI mode

Updating

Portable Hermes has two independent update channels. Updating one does not automatically update the other.

For the normal, safest maintenance path, close other Hermes windows and gateways, then double-click:

UPDATE.bat

Or run:

hermes.bat update --backup --yes

This updates from aivrar/portable-hermes-agent, makes a backup when requested, and preserves runtime folders such as .hermes/, .hermes/custom_tools/, .hermes/extensions/, extensions/, and python_embedded/.

If you also want newer upstream Hermes code, start Hermes after the Portable update and ask:

Check whether upstream Hermes Agent has updates. Do not install anything yet.

Then, if you want the available update, ask:

Update upstream Hermes Agent while preserving Portable Hermes. When finished, tell me whether I should restart.

Restart Hermes after a successful upstream update so the running process loads the new Python modules. A Git checkout can report an exact ahead/behind count; a release ZIP has no Git history, so it reports ZIP-overlay mode instead and can still install the latest upstream code.

Most users do not need daily updates. Run the Portable updater when a release, fix, or security notice is published (or every week or two), and check upstream weekly if you want newer Hermes features. Checking daily is optional.

See Keeping Portable Hermes Updated for the complete workflow, backups, release-ZIP behavior, and troubleshooting.

4. Connect an AI Model

Cloud (2 minutes, free):

1. File > API Key Setup > OpenRouter
2. Sign up at openrouter.ai (free, no credit card)
3. Paste your API key
4. Start chatting

Local (needs NVIDIA GPU):

1. Download LM Studio
2. Download a model, start the server
3. Tools > LM Studio in the GUI
4. Load model, click "Use for Chat"

Requirements

• Windows 10/11
• Internet connection (for cloud AI) or NVIDIA GPU 8GB+ (for local AI)
• No admin rights, no system Python, no Docker

Documentation

A searchable user guide is built into the agent — ask it anything or use the search_guide tool. The PDF manual is included in every release.

Key topics: getting started, API setup, the interface, permissions, LM Studio local models, extensions (TTS/Music/ComfyUI), all 100 tools, custom tool creation, workflows, and a glossary of AI terms.

Architecture

User
 |
 v
GUI (Tkinter) / CLI
 |
 v
Agent Bridge (threading, sessions)
 |
 v
AIAgent (run_agent.py)
 |
 +-- Tool Registry (100 tools)
 |    +-- LM Studio tools (SDK + HTTP)
 |    +-- Extension tools (Music, TTS, ComfyUI)
 |    +-- Workflow engine
 |    +-- Tool maker (dynamic creation)
 |    +-- Serper, GPU, Guide, etc.
 |    +-- Custom tools (user-created)
 |
 +-- LLM Provider
      +-- OpenRouter (cloud)
      +-- LM Studio (local, GPU)
      +-- Any OpenAI-compatible endpoint

Credits

• Base framework: NousResearch/hermes-agent (MIT License)
• Extension modules: aivrar — portable-tts-server, portable-music-server, comfyui-portable-installer
• Custom tools, GUI, and integrations: Built with Claude Code

License

MIT License — see LICENSE for details.

Original framework copyright (c) 2025 Nous Research.