How to set up a Hermes AI agent on Ubuntu via Hyper-V on Windows 11

Local AI on Windows series  ·  View all parts
← Part 1: Local AI stack with LM Studio and AnythingLLM  ·  Part 2 of 3  ·  Next: Part 3: Hermes in Docker with an admin dashboard →

Hermes is a local AI agent that can browse the web, read files, and execute tasks on your behalf. Running it inside a dedicated Ubuntu virtual machine via Hyper-V keeps it isolated from your main Windows environment — a clean separation between your daily work and an autonomous agent with browser access.

This guide covers the complete setup: creating the VM, fixing a common xrdp remote access issue, expanding disk space, installing Chrome with a debug port for the browser harness, and getting Hermes running and connected.

Prerequisites

• Windows 11 Pro, Enterprise, or Education — Hyper-V is not available on Windows 11 Home
• Ubuntu 22.04 or 24.04 LTS ISO — download from ubuntu.com
• At least 35 GB free disk space for the virtual hard disk
• 8 GB RAM minimum — allocate 4 GB to the VM, keep 4 GB for Windows

Step 1: Enable Hyper-V

Open PowerShell as administrator and run:

Enable-WindowsOptionalFeature -Online -FeatureName Microsoft-Hyper-V -All

Restart when prompted. After reboot, search for Hyper-V Manager in the Start menu to confirm it’s available.

Step 2: Create the Ubuntu VM

1. Open Hyper-V Manager
2. Click New → Virtual Machine
3. Name it (e.g. hermes-agent), choose Generation 2
4. Assign 4096 MB RAM, enable dynamic memory
5. Create a new virtual hard disk — start with 12 GB (we’ll expand it after install)
6. Attach the Ubuntu ISO as the installation media
7. Before starting: right-click the VM → Settings → Security → disable Secure Boot (required for Ubuntu)
8. Start the VM and complete the Ubuntu installation with default settings

Step 3: Expand disk space

12 GB fills up quickly once you install Chrome, Hermes, and its dependencies. Expand to 35 GB before going further.

In Hyper-V Manager (VM must be shut down):

1. Shut down the Ubuntu VM completely
2. In Hyper-V Manager, delete any checkpoints/snapshots first — disk expansion fails if checkpoints exist
3. Right-click the VM → Settings → Hard Drive → Edit
4. Choose Expand and set the new size to 35 GB
5. Click Finish

Inside Ubuntu (after booting back up):

sudo apt install -y cloud-guest-utils
sudo growpart /dev/sda 1
sudo resize2fs /dev/sda1

Verify with df -h — the root partition should now show ~35 GB.

Step 4: Set up remote desktop access with xrdp

Hyper-V’s default console is basic. xrdp gives you a proper remote desktop connection from Windows with clipboard support.

sudo apt update
sudo apt install -y xrdp
sudo systemctl enable xrdp

Important: fix the vsock issue. By default, Hyper-V configures xrdp to listen on a Hyper-V internal socket (vsock) rather than a standard TCP port. This makes it unreachable from a regular RDP client. Open the config file:

sudo nano /etc/xrdp/xrdp.ini

Find the port line under [Globals] — it will look something like port=vsock://-1:3389. Change it to:

port=3389

Save, then restart xrdp:

sudo systemctl restart xrdp

Get the VM’s IP address:

ip a | grep "inet "

On Windows, open Remote Desktop Connection and connect to that IP. Log in with your Ubuntu username and password.

Step 5: Install Chrome with a remote debugging port

Hermes controls the browser through Chrome’s DevTools Protocol (CDP). You need Chrome installed and launched with a debug port open.

Install Chrome:

cd ~
wget https://dl.google.com/linux/direct/google-chrome-stable_current_amd64.deb
sudo apt install -y ./google-chrome-stable_current_amd64.deb

Start Chrome with the debug port:

google-chrome --remote-debugging-port=9222 --remote-allow-origins=* --user-data-dir=/tmp/chrome-hermes

Leave this terminal open. Chrome needs to be running with this flag every time Hermes starts a browser session. You can create a shell alias or a startup script to simplify this later.

Step 6: Install Hermes

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

After installation, run the setup wizard:

hermes setup

The wizard will ask for your preferred LLM (you can point it to a local LM Studio server or an API key), your working directory, and browser preferences. Complete all steps before proceeding.

Step 7: Connect the browser harness

With Chrome running on port 9222, tell Hermes where to find it. Open ~/.hermes/config.yaml and add or update the browser section:

browser:
  cdp_url: http://localhost:9222

Start Hermes:

hermes

Inside a Hermes session, connect the browser harness:

/browser connect

If Chrome is running with the debug port open, Hermes will confirm the connection and browser-based tasks become available.

Step 8: First test

With everything running, try a simple browser task to confirm the full stack works:

“Open factnetize.com and tell me the title of the most recent article.”

Hermes should launch a browser action, navigate to the URL, read the page, and return the result. If it does, the CDP connection is working correctly.

Troubleshooting

RDP connection refused from Windows
Almost always the vsock issue in xrdp.ini. Double-check that the port line reads exactly port=3389 with no other value, and that you restarted xrdp with sudo systemctl restart xrdp after saving.

sudo asks for a password but nothing appears when typing
This is normal Linux behaviour — sudo does not display characters or asterisks while you type. Just type your password and press Enter.

Disk expansion fails in Hyper-V Manager
The Edit button is greyed out if the VM has checkpoints. In Hyper-V Manager, look at the bottom panel for the Checkpoints section, right-click each checkpoint and delete it. Wait for the merge to complete (the VHDX file size will stop changing), then try Edit again.

Caret ^ character on Belgian AZERTY keyboard in terminal
The ^ key on AZERTY is a dead key — press it followed by a space to produce a literal caret. Alternatively, rewrite commands to avoid the character entirely.

Hermes can’t find Chrome / CDP connection fails
Confirm Chrome is running with the --remote-debugging-port=9222 flag — check with ps aux | grep chrome. Also verify the port is open: sudo ss -tlnp | grep 9222. If Chrome is running but the port isn’t listed, the flag wasn’t passed correctly.

Conclusion

A Hyper-V Ubuntu VM gives you a contained environment for running autonomous AI agents: isolated from your Windows file system, easy to snapshot before experiments, and disposable if something goes wrong. The xrdp fix is the most common stumbling block — once that’s resolved, the rest of the setup is straightforward.

From here, you can experiment with giving Hermes longer-running tasks, connect it to a local LM Studio model for fully offline operation, or extend the browser harness to automate repetitive web workflows.

Featured image by Mohammad Rahmani on Unsplash.

Featured image by Mohammad Rahmani on Unsplash.