How to Install Hermes Agent with LM Studio (2026)

What Hermes Agent Does and Why LM Studio Fits the Setup

Hermes Agent (NousResearch/hermes-agent, MIT license) is an autonomous AI agent that runs as a long-lived background process. Unlike chatbots that answer one question at a time, it executes sequences of tool calls: browsing the web, reading and writing files, running terminal commands, and sending messages through connected gateways.

Hermes maintains four components on disk:

• `~/.hermes/SOUL.md` stores your identity and preferences. Loaded at every startup as the primary system context.
• `~/.hermes/memories/` holds fact-based memories extracted from sessions and retrieved by relevance on each run.
• `~/.hermes/skills/` holds step-by-step procedures the agent writes for itself and reuses across sessions.
• The gateway layer handles connections to Telegram, Discord, Slack, WhatsApp, Signal, and email for remote task submission.

Hermes uses any OpenAI-compatible API as its inference backend. LM Studio and Ollama both qualify. The choice between them is mostly practical:

For Windows users, LM Studio removes the WSL2 dependency entirely. For anyone who prefers visual model management over a command line, the LM Studio catalog and one-click download flow is faster to set up than Ollama's pull commands. The inference quality and Hermes capabilities are identical once both backends are configured.

Install LM Studio and Load a Tool-Capable Model

LM Studio 0.3.6 or later is required for tool-calling support. Earlier builds expose the chat completions API but do not process function-call schemas reliably, which causes Hermes to stall on tool-dependent tasks.

Step 1: Download and Install LM Studio

Download the installer for your platform from lmstudio.ai. LM Studio ships native builds for macOS (Intel and Apple Silicon), Windows 10/11 (x64), and Linux (AppImage and deb). Run the installer and launch LM Studio.

Confirm the version meets the requirement:

In LM Studio, go to Help and check that the version shown is 0.3.6 or later. If not, download the latest build from lmstudio.ai/download before proceeding.

Step 2: Choose and Download a Model

Hermes requires a model with native tool-calling (function-calling) support and at least 64K context. These models work reliably in LM Studio with Hermes Agent as of mid-2026:

In LM Studio's search bar, type the model name (for example "Gemma 4 E4B Instruct") and click Download. The download runs in the background. Wait for the status indicator to show 100%.

Step 3: Set Context Length to 65,536

This is the step that causes most failed setups. LM Studio's default context for many models is 2,048 or 4,096 tokens. Hermes rejects any model serving fewer than 64,000 tokens at startup.

In LM Studio, click the model you downloaded from the sidebar or model picker. Next to the model name, click the gear icon to open model settings. Find the field labeled "Context Length" and change the value to `65536`. Click Load Model and wait for the status indicator to confirm the model is ready.

If your machine's RAM cannot sustain 64K context at the model size you selected, try a smaller model or reduce to 32,768 tokens. Hermes will still launch, but very long multi-step tasks may hit the limit mid-session.

Step 4: Enable the Local Server

In LM Studio, open the Developer tab (sometimes labeled Local Server in newer builds). Click Start Server. The status panel should show:

Server running on http://localhost:1234

Leave this window open while you use Hermes. LM Studio must be running with the server active for every Hermes session.

Confirm the server is responding before moving on:

curl http://localhost:1234/v1/models

Expected output (abbreviated):

{
  "data": [
    { "id": "gemma-4-e4b-instruct", "object": "model" }
  ]
}

If you see the model listed, the server is working. Note the exact model ID string shown in the response; you will paste it into Hermes during setup.

Install Hermes Agent on Linux, macOS, or Windows

Hermes Agent installs with a one-line command on all three platforms. The installer manages the Python 3.11 dependency via `uv`, so you do not need Python pre-installed.

Linux and macOS

curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash

The script installs Hermes, sets up the `~/.hermes/` configuration directory, and adds the `hermes` command to your shell. Close and reopen your terminal, then verify:

hermes --version
# Expected: hermes v0.16.0 (or newer)

Windows (PowerShell — no WSL2 required)

irm https://hermes-agent.nousresearch.com/install.ps1 | iex

Run this in a PowerShell terminal opened as your regular user (not as Administrator). After the installer finishes, restart the terminal and confirm:

hermes --version
# Expected: hermes v0.16.0 (or newer)

Post-Install Dependencies

After the main install, run the post-install step to set up browser automation and other optional tools:

hermes postinstall

This installs Playwright and its Chromium browser, which Hermes uses for web browsing tasks. It is optional but recommended if you plan to use web research in agent tasks. The step takes 2-3 minutes on a standard connection.

Check for any missing components:

hermes doctor
# Expected output shows each component as OK or lists what to install

Connect Hermes Agent to LM Studio

With LM Studio running on port 1234 and a model loaded, run the Hermes setup wizard to connect the two:

hermes setup

The wizard prompts you for a provider. When you see the provider list, select "LM Studio" if it appears as a named option (available in Hermes v0.14+). If it does not appear in your version, choose "Custom OpenAI-compatible endpoint" instead.

For the endpoint URL, enter:

http://localhost:1234/v1

For the API key prompt, leave the field blank and press Enter, or enter any non-empty string such as `lm-studio`. LM Studio does not validate API keys for local connections. Hermes requires the field to be non-empty in some versions, which is why a placeholder value works.

For the model name, paste the exact model ID you noted from the `curl` command in Step 4. For Gemma 4 E4B this typically looks like `gemma-4-e4b-instruct` or a similar string matching what LM Studio returned from `/v1/models`. Using the wrong name results in a "model not found" error on the first request.

For the context length prompt, leave it blank. Hermes will auto-detect the context from LM Studio's server response. This is the safest option because it reads the value you set in LM Studio rather than setting an independent limit that may not match.

Manual Config (Alternative to the Wizard)

If you prefer editing the config file directly, open `~/.hermes/config.yaml` and add:

model:
  default: lmstudio

providers:
  lmstudio:
    type: openai
    base_url: "http://127.0.0.1:1234/v1"
    api_key: "lm-studio"
    model: "gemma-4-e4b-instruct"

Replace the `model` value with the exact model ID from LM Studio. Save the file. Hermes reads this on every startup, no restart of Hermes itself is needed.

To verify the connection:

hermes ping
# Expected: Connected to lmstudio via http://127.0.0.1:1234/v1 (gemma-4-e4b-instruct, 65536 tokens)

A successful ping confirms that Hermes can reach LM Studio, that the model is loaded, and that the context length meets the 64K minimum.

Configure SOUL.md and Run Your First Hermes Task

SOUL.md (`~/.hermes/SOUL.md`) is Hermes's identity file. Loaded at every startup as the first block of the system prompt, it defines who the agent is, what it knows about you, and how it should behave. Hermes writes to it automatically over time, but adding a few lines at setup time improves output quality from the first session.

Open the file in any text editor:

# Linux / macOS / Windows (WSL or native)
open ~/.hermes/SOUL.md        # macOS
notepad %USERPROFILE%.hermesSOUL.md   # Windows
nano ~/.hermes/SOUL.md        # Linux

A minimal useful SOUL.md for a new setup:

# Identity
You are Hermes, a local AI agent running via LM Studio on this machine.

# About the user
Name: [your name]
Timezone: [your timezone, e.g. UTC+1]
Primary language: English

# Behavior
- Be concise but technically accurate.
- Use tools when they significantly improve answer quality.
- Ask a clarifying question when the request is ambiguous rather than guessing.
- Prefer Markdown for multi-step instructions and code.

# Capabilities
You can call tools provided by Hermes Agent: web search, filesystem read/write,
terminal commands (with user approval), and messaging gateways.
All inference runs locally via LM Studio. No data leaves this machine unless
a tool explicitly contacts an external service.

Save the file. Hermes will include this on the next run.

First Task

Start Hermes in terminal mode:

hermes

The agent loads SOUL.md, connects to LM Studio, and shows a prompt. Try a simple tool-calling task to confirm the setup works end to end:

>>> List the 5 largest files in my home directory and tell me their sizes.

Hermes should call the filesystem tool, retrieve the results, and summarize them. If you see the tool call execute and a response come back with actual file names and sizes, the setup is complete.

Gateway Setup (Optional)

To control Hermes via Telegram or Discord, run the gateway setup:

hermes gateway setup

The wizard prompts for a bot token. For Telegram: create a bot via @BotFather on Telegram and paste the token. For Discord: create an application in the Discord developer portal and paste the bot token. Once configured, start the gateway:

hermes gateway run

All messages sent to the bot are routed to Hermes, which uses LM Studio as the inference backend. For 24/7 operation, run the gateway in a background `tmux` or `screen` session, or set it up as a systemd service on Linux.

Also see the Hermes Agent with Ollama guide for a comparison of how the gateway behaves with Ollama instead of LM Studio, and the Ollama vs LM Studio comparison for a full feature breakdown between the two local inference backends.

Troubleshooting

Frequently Asked Questions