aivrar/portable-hermes-agent

# GitHub Repository: aivrar/portable-hermes-agent

**URL:** https://github.com/aivrar/portable-hermes-agent
**Author:** aivrar
**Description:** Hermes Agent made portable desktop for Windows — 100 tools, GUI, local models via LM Studio, TTS, Music, ComfyUI, workflows, tool maker. No install. No Docker. No admin rights.
**Homepage:** 
**Language:** Python

## Stats
- Stars: 171
- Forks: 35
- Open Issues: 2
- Commits: 2948
- Created: 2026-03-15T23:31:44Z
- Updated: 2026-06-18T10:10:57Z
- Pushed: 2026-05-22T03:35:25Z

## README
# 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](https://github.com/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

| Toolset | Tools | What It Does |
|---------|-------|-------------|
| **LM Studio** | 10 | Load/unload models, search HuggingFace, tokenize, embed, direct chat |
| **Music** | 7 | Generate music, manage models, GPU workers, output library |
| **TTS** | 7 | Text-to-speech, 10 voice models, voice cloning, job management |
| **ComfyUI** | 7 | Image generation, instance management, model/node browsing |
| **Workflows** | 6 | Create, run, schedule, and manage multi-step automation pipelines |
| **Tool Maker** | 3 | Dynamically create API wrapper or Python handler tools at runtime |
| **Serper** | 1 | Google-quality search via Serper.dev API |
| **Guide** | 1 | Searchable built-in user manual |
| **GPU** | 1 | NVIDIA GPU status (memory, temp, utilization) |
| **Model Switcher** | 1 | Switch between cloud and local AI models |
| **Hermes Update** | 2 | Pull upstream updates + auto-reinject custom tools |

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](https://github.com/aivrar):

| Extension | Port | Models | GPU |
|-----------|------|--------|-----|
| **[TTS Server](https://github.com/aivrar/portable-tts-server)** | 8200 | Kokoro, XTTS, Dia, Bark, Fish, + 5 more | 4 GB+ |
| **[Music Server](https://github.com/aivrar/portable-music-server)** | 9150 | MusicGen, Stable Audio, ACE-Step, Riffusion | 4 GB+ |
| **[ComfyUI](https://github.com/aivrar/comfyui-portable-installer)** | 5000 | SD 1.5, SDXL, Flux, 100+ registry models | 6 GB+ |

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. Install
```batch
install.bat
```
Downloads embedded Python 3.13, all dependencies, LM Studio SDK, and Node.js tools. No admin rights needed.

### 2. Launch
```batch
hermes.bat          :: CLI mode
hermes_gui.bat      :: GUI mode
```

### 3. 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](https://lmstudio.ai)
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](https://github.com/aivrar/portable-hermes-agent/releases/latest) 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](https://github.com/NousResearch/hermes-agent) (MIT License)
- **Extension modules**: [aivrar](https://github.com/aivrar) — portable-tts-server, portable-music-server, comfyui-portable-installer
- **Custom tools, GUI, and integrations**: Built with [Claude Code](https://claude.ai/claude-code)

---

## License

MIT License — see [LICENSE](LICENSE) for details.

Original framework copyright (c) 2025 Nous Research.