Skip to content

Getting Started

Jump to bottom
aivrar edited this page Jul 29, 2026 · 3 revisions

Part 1: What is Hermes Agent?

The Big Picture

Hermes Agent is a personal AI assistant that runs as a desktop application on your Windows computer. Unlike web-based AI chatbots (like ChatGPT), Hermes runs locally and can actually interact with your computer — reading files, running commands, browsing the web, generating images and music, and automating tasks.

Think of it as having a smart assistant sitting at your computer who can:

  • Answer questions — about anything, using the latest AI models
  • Search the web — find information, read articles, research topics
  • Work with files — read, write, edit, and organize files on your computer
  • Browse websites — navigate pages, fill forms, take screenshots
  • Generate images — create artwork, logos, illustrations from text descriptions
  • Generate music — compose songs, sound effects, jingles from descriptions
  • Generate speech — convert text to natural-sounding audio with voice cloning
  • Run code — write and execute Python scripts, automate repetitive tasks
  • Control local AI models — load, manage, and switch between AI models on your GPU
  • Build custom tools — create new capabilities on the fly
  • Automate workflows — chain multiple actions into repeatable pipelines
  • Control smart home devices — via Home Assistant integration
  • Send messages — via Telegram, Discord, email, and more

How It Works

Hermes connects to an AI model (either online or running locally on your GPU) and uses that model as its "brain" to understand your requests and decide what to do. The model can call "tools" — specialized functions that perform actions like searching the web, reading files, or generating images.

You type a message in plain English, and Hermes figures out what tools to use, in what order, to accomplish your request. It shows you what it's doing at each step.

What You Need

Minimum requirements:

  • Windows 10 or 11
  • Internet connection (for cloud AI models)
  • A free OpenRouter API key (takes 2 minutes to get)

For local AI models (optional):

  • NVIDIA GPU with 8GB+ VRAM (RTX 3060 or better)
  • LM Studio (free download from lmstudio.ai)

For extensions (optional):

  • NVIDIA GPU with 4-6GB+ VRAM for TTS, Music, or Image generation

Part 2: First Launch — Getting Started

Step 0: Download and Unzip

  1. Open the latest Portable Hermes Agent release
  2. Download portable-hermes-agent-*.zip
  3. Extract the ZIP to a normal folder such as C:\PortableHermes
  4. Keep the extracted folder together; do not move individual files out of it

The release page also includes the PDF manual. The latest release tag is connected to the exact commit used to build the ZIP asset.

Step 1: Launch Hermes

Double-click START.bat. On first launch it prepares the portable Python environment and dependencies inside the extracted folder, then opens Hermes. Later, you can use START.bat again or launch hermes_gui.bat for the desktop GUI and hermes.bat for the command-line interface.

You'll see:

  • A sidebar on the left (for conversation sessions)
  • A chat area in the center (where you'll talk to Hermes)
  • An input box at the bottom (where you type messages)
  • A menu bar at the top (File, Tools, Help)
  • A status bar at the bottom (shows current model and status)

Step 2: Connect to an AI Model

Hermes needs a connection to an AI model to function. You have two paths:

Path A: Cloud AI via OpenRouter (Easiest — 2 minutes, no GPU needed)

OpenRouter is a service that gives you access to dozens of AI models through a single API key. Many models are completely free.

  1. The API Setup Wizard will open automatically on first launch
    • If it doesn't, go to File > API Key Setup
  2. Click the OpenRouter row
  3. Click "Get Key" — this opens the OpenRouter website in your browser
  4. On the OpenRouter website:
    • Click Sign Up (you can use Google, GitHub, or email)
    • No credit card is required
    • After signing in, you'll see a Dashboard
    • Click "Create Key" (or go to the Keys page)
    • A key will appear that starts with sk-or-...
    • Click the copy button next to the key
  5. Go back to the Hermes wizard
    • The key should auto-paste (Hermes watches your clipboard)
    • If it didn't, click "Paste from Clipboard"
    • Click "Save & Next"
  6. You're connected! Start chatting.

Which model should I use?

The default model is google/gemini-2.5-flash which is:

  • Completely free (no cost per message)
  • Very fast (responds in 1-3 seconds)
  • Smart enough for most tasks

Other good free options:

  • deepseek/deepseek-chat-v3 — excellent at reasoning and coding
  • meta-llama/llama-4-maverick — Meta's latest open model

If you want the most capable models (small cost per message):

  • anthropic/claude-sonnet-4 — excellent at writing and analysis
  • google/gemini-2.5-pro — great at complex reasoning
  • openai/gpt-4o — OpenAI's flagship model

You can change your model anytime in File > Settings > Model tab.

Path B: Local AI via LM Studio (Private — needs NVIDIA GPU)

LM Studio lets you run AI models entirely on your own computer. Nothing is sent to the internet. This is ideal if you care about privacy or want to experiment with open-source models.

Prerequisites:

  • NVIDIA GPU with at least 8GB VRAM (RTX 3060 or better)
  • LM Studio installed (free from https://lmstudio.ai)

Setup steps:

  1. Download and install LM Studio from https://lmstudio.ai
  2. Open LM Studio and let it detect your GPU
  3. Download a model:
    • In LM Studio, go to the Discover tab
    • Search for a model (recommendations below)
    • Click Download — it will download the model file (1-10 GB depending on model)
    • Wait for the download to complete
  4. Start the server:
    • Go to the Developer tab in LM Studio
    • Click Start Server
    • Note the port number (default is 1234, yours might be different)
    • The server status should show "Running"
  5. Configure Hermes:
    • In Hermes, go to File > Settings
    • In the Model tab, type the model name
    • Click Save & Close
    • Or, go to Tools > LM Studio to use the visual model manager

Recommended starter models by GPU size:

Your GPU Recommended Model VRAM Used
8 GB (RTX 3060/4060) Qwen 2.5 7B Q4 ~5 GB
8 GB Phi-4 Mini Q8 ~4 GB
12 GB (RTX 3060 12GB) Llama 3.1 8B Q6 ~7 GB
12 GB Qwen 2.5 14B Q4 ~9 GB
24 GB (RTX 3090/4090) Qwen 2.5 32B Q4 ~20 GB
24 GB Llama 3.1 70B Q2 ~22 GB

What do Q4, Q6, Q8 mean? These are quantization levels — how much the model is compressed:

  • Q4 = smallest file, fastest, slightly less accurate
  • Q6 = good balance of size and quality
  • Q8 = largest file, slowest, most accurate
  • FP16 = uncompressed (rarely needed, very large)

For most users, Q4 or Q6 is the sweet spot.

Path C: Both Cloud and Local (Recommended for power users)

You can have both configured and switch between them:

  • Use cloud AI (OpenRouter) for complex tasks that need the smartest models
  • Use local AI (LM Studio) for private conversations or offline work

To switch, just tell Hermes:

  • "Switch to my local model" — uses LM Studio
  • "Switch to OpenRouter" — uses cloud AI
  • Or use File > Settings to change the model

Step 3: Set Up Optional API Keys

Each key unlocks additional abilities. None of them are required — Hermes works with just the OpenRouter key. You can add these anytime later.

Service What It Unlocks Free Tier How to Get
OpenRouter All AI conversations Many free models openrouter.ai/keys
Firecrawl Web search + page reading 500 credits/month firecrawl.dev
Serper Google-quality search results 2,500 searches/month serper.dev
FAL.ai Image generation (FLUX) $10 free credits fal.ai/dashboard/keys
Browserbase Cloud browser automation 1000 sessions/month browserbase.com

To set up any key individually:

  1. Go to File > API Key Setup
  2. Click the "Set up" link next to any service
  3. Follow the step-by-step instructions

Step 4: Keep Portable Hermes Updated

Portable Hermes has two independent update paths:

  1. Portable distribution update: close Hermes and run UPDATE.bat. This is the normal maintenance path and updates the tested Portable distribution from aivrar/portable-hermes-agent.
  2. Optional upstream Hermes update: start Hermes, ask it to check for upstream updates, and choose whether to install newer core code from NousResearch/hermes-agent. Restart Hermes after a successful upstream update.

You do not need to update every day. Use the Portable updater for releases, fixes, and security notices; check upstream weekly if you want newer features. See Keeping Portable Hermes Updated for the commands, recommended order, release-ZIP behavior, backups, and troubleshooting.

Part 10: Settings Reference

Environment Variables (.env file)

The .env file in the Hermes directory contains all configuration. You can edit it directly or use the GUI.

Core settings:

Variable Description Example
LLM_MODEL The AI model to use google/gemini-2.5-flash
OPENAI_BASE_URL API endpoint URL https://openrouter.ai/api/v1
OPENROUTER_API_KEY OpenRouter API key sk-or-v1-...

Optional API keys:

Variable Description
FIRECRAWL_API_KEY Web search and page reading
SERPER_API_KEY Google search via Serper.dev
FAL_KEY Image generation (FAL.ai)
BROWSERBASE_API_KEY Cloud browser automation
GITHUB_TOKEN Skills Hub (higher rate limits)

Extension ports:

Variable Default Description
TTS_SERVER_URL http://localhost:8200 TTS server address
MUSIC_SERVER_URL http://localhost:9150 Music server address
COMFYUI_URL http://localhost:8188 ComfyUI address

Glossary

Term Plain English Explanation
API A way for programs to talk to each other. An API key is like a password that lets Hermes use an online service.
API Key A long code (like a password) that gives Hermes permission to use an online service. You get these from the service's website.
Model The AI "brain." Different models are good at different things. Think of them like different experts — one might be great at writing, another at math.
GPU Your graphics card. Originally designed for gaming, but perfect for running AI models. NVIDIA GPUs are required for local AI.
VRAM Memory on your GPU. Determines how big an AI model you can run. More VRAM = bigger/smarter models.
Token A piece of text, roughly 4 characters or 3/4 of a word. AI models process text in tokens. "Hello world" = 2 tokens.
Context Length How much text the AI can "see" at once. Like the AI's short-term memory. 4096 tokens ≈ 3,000 words.
GGUF A file format for AI models that run on your computer. Like .mp3 is for music, .gguf is for AI models.
Quantization Compression for AI models. Q4 = very compressed (small, fast), Q8 = light compression (bigger, more accurate). Like JPEG quality settings for images.
Inference When the AI generates a response. "Running inference" = "the AI is thinking."
Tool A specific action Hermes can take — like searching the web, reading a file, or generating an image. Portable Hermes exposes 96 core tools, plus extension and custom tools.
Toolset A group of related tools. The "web" toolset includes web_search and web_extract.
Workflow A saved sequence of tool calls that run automatically. Like a macro or recipe.
Extension An add-on module that gives Hermes new abilities (TTS, Music, Image Generation). Each is a separate program that runs alongside Hermes.
OpenRouter An online service that lets you use many different AI models through one API key. Like a universal remote for AI.
LM Studio A free program for running AI models on your own computer. Like a music player, but for AI models.
Prompt The text you send to an AI model. Your message is the prompt.
Streaming When the AI response appears word-by-word instead of all at once.
Session A single conversation from start to finish. Each session is saved separately.
Sub-agent A separate AI instance that Hermes creates to work on a specific task, then reports back. Like delegating work to an assistant.

Getting Help

  • Ask Hermes! Type your question in the chat — Hermes can search this guide for answers using the search_guide tool
  • File > API Key Setup — Check which services are connected
  • Tools > Permissions — Adjust what Hermes can do if something is blocked
  • Tools > Extensions — Check if extension servers are running
  • Tools > LM Studio — Manage local AI models
  • Visit the GitHub repository for bug reports and feature requests

Clone this wiki locally