Install Hermes Agent on Windows with WSL2, Ollama, and Telegram

If you want to run Hermes Agent on Windows, the practical path is WSL2 + Ubuntu + Ollama + a local model, then optionally connect Telegram for remote access. This keeps Windows as the host while giving Hermes Agent a Linux-style environment to run in.

Quick Answer

Install Ubuntu in WSL2, verify that Ollama can serve a model inside the environment where Hermes Agent will run, and complete the local Hermes setup before adding Telegram. The most important check is endpoint reachability: http://127.0.0.1:11434 works only when Ollama is reachable from the same WSL environment. If Ollama runs on Windows instead, test the Windows host address from WSL before changing Hermes configuration.

The low-friction setup is:

• keep Windows as the host system
• run Ubuntu inside WSL
• use Ollama to serve the local model
• let Hermes Agent connect directly to the local Ollama endpoint

This approach keeps the environment relatively clean, lets you run most commands in a Linux-style workflow, and avoids preparing a separate Linux machine.

Hermes Agent Windows Setup Flow

You can split the setup into 4 steps:

1. Enable WSL and install Ubuntu
2. Install Python, Node.js, Git, and other basics inside Ubuntu
3. Install Ollama and pull a local model
4. Install Hermes Agent, then connect Telegram

If your goal is simply to get Hermes Agent running first, by the end of step 3 you are already close.

1. Install WSL and Ubuntu

Run this in PowerShell with administrator privileges:

1

wsl --install

After the installation finishes, restart the PC, then continue with Ubuntu:

1

wsl --install -d Ubuntu

After that, open Ubuntu in WSL. Most of the remaining commands are run there.

2. Update Ubuntu and install the base environment

Update the system first:

1
2

sudo apt update
sudo apt upgrade -y

Then install Python, extraction tools, Node.js, and Git.

Install Python

1

sudo apt install python3-pip python3-venv -y

Install zstd

1

sudo apt install -y zstd

Install Node.js

1
2

curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -
sudo apt install -y nodejs

Install Git

1
2

sudo apt update
sudo apt install -y git

You can quickly verify the installation with:

1
2
3

node -v
npm -v
git --version

3. Install Ollama and pull Gemma 4

Install Ollama:

1

curl -fsSL https://ollama.com/install.sh | sh

If you want a local model for Hermes Agent, starting with Gemma 4 is reasonable.

For example:

1

ollama run gemma4:e4b

If your machine is weaker, you can also try:

1

ollama run gemma4:e2b

Larger variants include:

1
2

ollama run gemma4:26b
ollama run gemma4:31b

For most normal Windows + WSL setups, gemma4:e4b is usually the more practical starting point.

4. Install and configure Hermes Agent

Install it with:

1

curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash

After installation, point it to the local Ollama endpoint:

1

http://127.0.0.1:11434

Use the local model name you actually installed, for example:

1

gemma4:e4b

If the installer asks you to refresh the shell, run:

1

source ~/.bashrc

Verify Each Layer Before Adding Telegram

Test the stack from the bottom up so one connection error does not look like an Agent problem:

1. In WSL, run wsl.exe --status from PowerShell or uname -a inside Ubuntu to confirm the environment is active.
2. Run ollama list and then ollama run <model> to confirm the model name and local inference work.
3. From the same environment as Hermes Agent, request http://127.0.0.1:11434/api/tags and confirm Ollama returns a model list.
4. Run hermes setup, enter the verified endpoint and exact model name, then start hermes locally.
5. Only after local chat works, run hermes setup gateway and add the Telegram credentials.

If the API request fails but ollama run works in a Windows terminal, Ollama and Hermes are probably running on opposite sides of the Windows/WSL boundary. Use the Windows host address that WSL can reach, and make sure Ollama is listening on an interface permitted by your firewall. If the endpoint works but Hermes reports that the model is missing, copy the exact name shown by ollama list, including its tag.

Common Hermes Agent commands

These are the commands you will use most often:

Start

1

hermes

Re-enter setup

1

hermes setup

Configure the chat gateway

1

hermes setup gateway

Update

1

hermes update

Basic Telegram connection steps

If you want Hermes Agent to send and receive messages through Telegram, the core step is still:

1

hermes setup gateway

Then prepare the two Telegram-side items you need:

• create a bot with BotFather
• get your User ID with @userinfobot

Once you have those basics, continue filling them into the Hermes Agent gateway setup.

Who this setup fits

This workflow is a good fit if:

• Windows is your main desktop system
• you do not want to maintain a separate Linux host
• you want to get a local Agent running first, then expand to chat platforms
• you prefer local models instead of depending on cloud APIs

If you mainly want to experience a local Agent rather than build a full production deployment immediately, this path is already practical enough.

A few things to keep in mind

• WSL is still a compatibility layer, so in extreme cases it may not behave exactly like native Linux
• whether a large model runs smoothly still depends on your RAM, VRAM, and CPU / GPU
• gemma4:e4b is a realistic starting point, but actual experience still depends on the machine
• Hermes Agent platform integration is an extension step; getting the local model path working first, then adding Telegram, is usually more stable

Original reference

This post is rewritten and organized based on:

• Xchaoge Blog: 太简单了！Hermes Agent 本地部署（无需API）接入 Telegram + 微信

Connect Ollama and Codex OSS as a Local Agent in WSL

When deploying local Agents on Windows, the most worry-free structure is usually not to scatter the model service, Docker, terminal and coding tools in Windows, WSL and multiple virtual environments, but to put them into the same WSL2 Ubuntu distribution:

1
2
3
4
5
6

Windows
└─ WSL2 Ubuntu
   ├─ Ollama：本地模型服务
   ├─ 本地模型：聊天、代码、Embedding
   ├─ Codex OSS：Agent 客户端
   └─ 项目目录：代码、Git、测试命令

In this way, Ollama and Agent communicate directly through localhost in WSL, and the path, permissions and logs are all in the Linux environment. The Windows side can continue to access the project using Windows Terminal, VS Code Remote WSL, or Explorer.

Let’s talk about the conclusion first

The minimum available route is:

1
2
3
4
5
6

安装 WSL2 Ubuntu
-> 在 Ubuntu 安装 Ollama 和一个小模型
-> 在 Ubuntu 内验证 ollama run
-> 用 codex --oss --local-provider ollama 启动 Agent
-> 先执行只读任务
-> 再逐步允许修改、测试和工具调用

Don’t give the local Agent full permissions from the beginning, and don’t go after the largest model first. It is more important to first use a model verification process that can run stably than to deal with complex agents, remote ports, and multi-agent orchestration first.

Step 1: Install WSL2 and Ubuntu

Execute in Administrator PowerShell on Windows:

1

wsl --install

After rebooting, Ubuntu will be installed by default. When you open Ubuntu for the first time, follow the prompts to create a Linux username and password.

Confirm that the distribution uses WSL2:

1

wsl -l -v

If the old distribution is still version 1, you can convert:

1

wsl --set-version Ubuntu 2

Enter Ubuntu:

1

wsl

Most of the subsequent commands are executed in the Ubuntu terminal, not PowerShell.

Step 2: Prepare Ubuntu basic environment

After entering WSL, update the system first:

1
2
3

sudo apt update
sudo apt upgrade -y
sudo apt install -y curl git ca-certificates

Confirm environment:

1
2
3

uname -a
pwd
git --version

It is recommended that the project be placed in the Linux file system, for example:

1
2

mkdir -p ~/projects
cd ~/projects

Do not run high-frequency Git, Node.js, Python virtual environments and large-scale dependencies under /mnt/c/.... Cross-file system access can be slower on some development tasks and more likely to encounter permissions and file listening differences. When you need to open a project from Windows, you can use VS Code’s Remote WSL feature.

Step 3: Install and verify Ollama within WSL

Follow the Ollama Linux installation method:

1

curl -fsSL https://ollama.com/install.sh | sh

First start the service in the current terminal:

1

ollama serve

Open another WSL terminal, download and test a model:

1
2

ollama pull qwen3:8b
ollama run qwen3:8b

Model selection must be determined by your GPU memory or CPU/memory. When there is no available GPU, use a smaller model to verify the process first; don’t mistake “large model files can be downloaded” for “this machine can perform smooth inference”.

Confirm service and model status:

1
2

ollama ls
ollama ps

If ollama run itself cannot output stably, solve the problem of model, video memory, driver or memory first, and then connect to Agent.

Step 4: Check if the WSL GPU is actually available

When you have an NVIDIA GPU, execute within WSL:

1

nvidia-smi

Being able to show the graphics card doesn’t mean Ollama has used the GPU, but it at least proves that WSL sees the driver. After starting the model, execute:

1
2

ollama ps
nvidia-smi

Observe whether the model uses GPU and whether the video memory increases.

If nvidia-smi does not exist or an error is reported, first check the NVIDIA driver, WSL version and GPU support of Windows. Do not rush to install the desktop Linux driver repeatedly in Ubuntu. WSL’s GPU support has its own driver link.

Step 5: Let Codex use local Ollama

Codex offers OSS mode with the option of Ollama or LM Studio as the local provider. Once Codex is installed and runnable within WSL, go into your project directory:

1

cd ~/projects/your-project

It is recommended to start with read-only permissions for the first time:

1

codex --oss --local-provider ollama --sandbox read-only

First give a task that does not modify the file:

1

阅读当前仓库的 README 和目录结构，说明启动、测试和构建命令。不要修改任何文件。

After confirming that the local model can understand the warehouse and the answer is stable, use the workspace write permission as needed. Don’t skip Git, testing, and permissions just because it’s a local model.

If you want to use Ollama as the default local provider, add ~/.codex/config.toml in the user-level Codex configuration:

1

oss_provider = "ollama"

Then use the following command:

1

codex --oss

Note that provider-related configuration should be placed in user-level configuration, not .codex/config.toml in the project. The project configuration should not covertly change your machine’s model provider.

Step 6: Enable systemd when resident services are required

New installations of WSL Ubuntu usually already use systemd by default. First check:

1

systemctl status

If systemd is not enabled in the current distribution, edit:

1

sudo nano /etc/wsl.conf

join in:

1
2

[boot]
systemd=true

Then go back to Windows PowerShell:

1

wsl --shutdown

Check systemctl status again after re-entering Ubuntu.

Whether to make Ollama a resident service depends on the installation method and whether you need a backend API. When you first start learning, it is easiest to keep a ollama serve terminal to see the logs; after it is confirmed to be stable, use systemd to manage the service.

Paths, ports and APIs within WSL

By default, the Ollama service uses:

1

http://localhost:11434

If the agent, script, and Ollama are all in the same WSL distribution, this local address will be used first, and there is no need to open the LAN port first.

Test API:

1

curl http://localhost:11434/api/tags

When it needs to be called in Windows programs, mobile phones or other devices on the local area network, the network exposure method, reverse proxy and authentication must be designed separately. Do not map exposed local model ports directly to the public network.

Recommended resource ratings

A larger model does not mean a more reliable Agent. For local Agents, command execution stability, context, tool calling capabilities, and task splitting methods also affect the results.

The easiest trap to step into

1. Windows and WSL each run a set of Ollama

This will make it difficult for you to tell which service the Agent is actually connected to. For initial deployment, it is recommended to run only one set of Ollama within WSL, and all testing is completed on the same WSL terminal.

2. Run all development tasks in /mnt/c

Accessible, but may not be ideal depending on installation, file listening, Git performance, and Linux permissions behavior. Prioritize active projects in ~/projects.

3. The local model allows writing files from the beginning

First use --sandbox read-only to verify whether the model understands the task. Once you enter the modification phase, you should also let it explain the plan before checking diffs, running tests, and using Git to retain fallback points.

4. There is no authentication after the port is opened.

Once a local API is allowed LAN access, it is no longer just a “service on your own computer.” At a minimum limit firewall sources and add authentication and HTTPS at the reverse proxy layer if necessary.

5. Thinking that if the installation is successful, it will automatically run in the background.

The foreground process exits when WSL is closed or the distribution is stopped. When long-term APIs are required, first confirm systemd, service status, and Windows/WSL operating policies.

Summarize

Windows WSL deploys local Agents. The most reliable first version is:

1
2
3
4
5

WSL2 Ubuntu
-> Ollama 跑通小模型
-> Codex OSS 模式只读分析仓库
-> Git 和测试验证
-> 再增加写权限、服务常驻和局域网 API

Keeping the model, agent, and code in the same WSL environment can reduce path, port, and permission issues by more than half. Wait until the minimal process is stable before considering Docker, multi-model routing, RAG, or remote access.

refer to:

• Microsoft Learn: Install WSL
• Microsoft Learn: WSL systemd
• Ollama Linux Documentation
• Codex OSS Local Provider
• Local large model API for Codex usage tutorial

Conclusion

If you want to deploy Hermes Agent locally on Windows with as little friction as possible, the smoother order is:

WSL -> Ubuntu -> Ollama -> Gemma 4 -> Hermes Agent -> Telegram

Get the local model running first, then add the gateway integration. That usually gives you a much higher success rate. For most users, this is easier to troubleshoot than piling on every component at the beginning, and it also leaves room for later expansion.

For the next troubleshooting step, see how to expose an Ollama API on a Windows LAN and how to troubleshoot Ollama GPU usage. For a broader overview before choosing this stack, read the Hermes Agent setup and OpenClaw comparison.

Alternative Backend: Qwen3.6, llama.cpp, and a Local API

Ollama is the easier starting point. Use llama.cpp when you need direct control over GGUF quantization, GPU offload, context, and the chat template. This path does not depend on one third-party quantization repository: download a Qwen3.6 GGUF from a trusted model card, choose a size your hardware can sustain, and record its checksum.

Build the CUDA backend inside WSL:

1
2
3
4
5

sudo apt update
sudo apt install -y git cmake build-essential
git clone https://github.com/ggml-org/llama.cpp.git
cmake -S llama.cpp -B llama.cpp/build -DGGML_CUDA=ON
cmake --build llama.cpp/build --config Release -j

Start with an 8K context and replace the model path. --n-gpu-layers 99 requests maximum offload; it does not guarantee enough VRAM. Reduce layers or use a smaller quantization after an OOM.

1
2
3
4
5
6

./llama.cpp/build/bin/llama-server \
  --model ~/models/qwen3.6-model.gguf \
  --n-gpu-layers 99 \
  --ctx-size 8192 \
  --host 127.0.0.1 \
  --port 8080

Verify the OpenAI-compatible API from the same WSL environment that runs Hermes:

1
2

curl http://127.0.0.1:8080/v1/models
curl http://127.0.0.1:8080/health

Run hermes setup, use http://127.0.0.1:8080/v1 as the custom endpoint, copy the actual ID from /v1/models, and enter only a local placeholder API key. Test chat first, then tool calls and file permissions. Text output with repeated tool-call failures usually points to model capability or chat-template mismatch, not a port issue.

For thinking controls, follow the model card and arguments supported by the installed llama.cpp version instead of copying an old JSON toggle. Change only one of model, context, GPU layers, or template at a time, and retain the last working command. Keep the service bound to 127.0.0.1; remote access needs authentication and TLS at a reverse proxy.