Install Hermes Agent on an Ubuntu Virtual Machine: Setup, Snapshots, and Recovery

A Hermes Agent install on an Ubuntu virtual machine takes four steps. Create an Ubuntu 24.04 VM, install a few packages, and run the official install script. Then choose a model provider with hermes model and run the gateway as a systemd service. Take a VM snapshot before the install and another after it works. If an update or the agent itself breaks something, you revert the snapshot and start again.

Who this is for: you want to try Hermes Agent, the open-source AI agent from Nous Research, without giving it access to your main computer.

Why run Hermes Agent in a virtual machine

Hermes Agent is not a chatbot in a browser tab. It runs shell commands, edits files, keeps memory and can act on a schedule. By default it runs those commands directly on the machine where you install it. The project's own security policy is blunt about this. It says, "The only security boundary against an adversarial LLM is the operating system."

A virtual machine gives the agent its own operating system. If it deletes the wrong folder or installs something odd, the damage stays inside the VM. Your laptop, your photos and your saved browser logins are not in reach. The security docs also suggest a separate machine or VM for maximum isolation. If you want the background on why a VM isolates more than a container, read containers vs virtual machines.

A VM also gives you snapshots. A snapshot saves the whole machine at one point in time. That is the best recovery tool you have for an agent that changes its own environment.

What you need

A hypervisor

Any desktop or server hypervisor works. If you are not sure what that word means, read what a hypervisor is first. Common choices:

• Proxmox VE on a spare PC or mini PC. Good if the agent should run around the clock. See what Proxmox VE is.
• VMware Workstation Pro or Fusion Pro on your desktop. As of October 2026, both are free for all use. Verify this on the Broadcom site.
• VirtualBox on Windows, Linux or macOS (check that your version supports your Mac's chip).

The guide to VMware vs VirtualBox vs Proxmox compares them for a desktop lab. On an Apple Silicon Mac, use an ARM build of Ubuntu in VMware Fusion. As of October 2026, the Hermes platform page lists Linux on both x86_64 and aarch64 as supported.

VM size

Nous Research publishes resource figures only for the Docker container. As of October 2026, those are 1 GB of RAM minimum and 2 to 4 GB recommended, 1 CPU core minimum and 2 recommended. Browser tools need at least 2 GB of RAM. A full VM also needs room for Ubuntu itself, so I suggest the sizes below. They are my suggestion, not an official figure.

Resource	Suggested VM size	Why
vCPUs	2	Matches the recommended container figure
RAM	4 GB	Ubuntu plus the agent plus browser tools
Disk	32 GB	OS, runtimes, logs, sessions and snapshot headroom
Network	NAT or bridged	The agent needs outbound internet only
GPU	None	Only needed if you run a local model

A model provider

Hermes Agent needs a language model. You can use a cloud provider such as OpenRouter, Anthropic, OpenAI or Nous Portal, with an API key. You can also run a local model through llama.cpp or Ollama. Note one hard rule: Hermes rejects models with less than 64,000 tokens of context. Ollama's default context is lower, so you must raise it. Check the providers page for the current list.

Step 1: Create the Ubuntu VM

Download Ubuntu Server 24.04 LTS from the Ubuntu website. Create a VM with the sizes above and install Ubuntu with default options. Turn on the OpenSSH server during setup so you can work from your own terminal.

Use Ubuntu 24.04. The Hermes docs say they test on the latest Ubuntu. As of October 2026, I found no official statement that Ubuntu 22.04 is tested.

Step 2: Prepare Ubuntu

Log in over SSH as your normal user, not root. Update the system and install the prerequisites:

sudo apt update && sudo apt upgrade -y
sudo apt install -y git curl tar libatomic1

The installer needs Git, curl, tar and SHA-256 tools. Ubuntu ships the SHA-256 tools already. The libatomic1 package is there for a reason. Early installs on minimal Ubuntu 24.04 images failed silently without it. The current installer adds it for you, but installing it first costs nothing.

Step 3: Take a clean snapshot

Shut down the VM and take a snapshot. Name it something plain, such as clean-ubuntu. This is your return point if the install goes wrong.

• Proxmox: select the VM, open Snapshots, click Take Snapshot.
• VMware: VM menu, Snapshot, Take Snapshot.
• VirtualBox: Machine Tools, Snapshots, Take.

Step 4: Run the Hermes Agent install script

Start the VM and run the official one-line installer from the Hermes installation docs:

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

Read any script before you pipe it to bash. You can download it first with curl -fsSL https://hermes-agent.nousresearch.com/install.sh -o install.sh, read it, then run bash install.sh.

The script brings its own pinned Python and Node.js runtimes. It does not use your system Node.js. As of October 2026, pip, PyPI and Homebrew installs are not supported, so use the script. When it finishes, reload your shell and start the agent:

source ~/.bashrc
hermes

Here is where the files go:

• Code: ~/.hermes/hermes-agent/
• Launcher: ~/.local/bin/hermes
• Data: ~/.hermes/, including config.yaml, .env (your API keys), memories, skills, sessions and state.db

Step 5: Choose a model and tools

Run the setup commands. You can do them one at a time or run the full wizard with hermes setup.

hermes model          # choose your provider and model
hermes tools          # choose which tools the agent may use
hermes config get     # check a setting

Start with few tools. Lock down the key file at the same time:

chmod 600 ~/.hermes/.env

Step 6: Run Hermes as a service

To keep the agent running after you log out, install the gateway as a systemd user service. Then turn on lingering so the service starts at boot without a login:

hermes gateway install
hermes gateway start
hermes gateway status
sudo loginctl enable-linger $USER

View the logs with journalctl --user -u hermes-gateway -f or hermes logs gateway -f.

Connect a chat app (optional)

The gateway can talk to you through Telegram, Discord, Slack, Signal, email and others. Run hermes gateway setup and follow the prompts. As of October 2026, the gateway denies every user who is not on an allowlist or paired. Keep it that way. Never set GATEWAY_ALLOW_ALL_USERS=true. Chat platforms need no inbound port on the VM.

Step 7: Snapshot the working agent

Once the agent answers you, shut down the VM and take a second snapshot, such as hermes-working. You now have two return points: a clean OS and a known-good agent.

Snapshots, backups and recovery

Snapshots and backups do different jobs. Use both.

Tool	What it saves	Use it when
VM snapshot	The whole VM: OS, agent code and data	Before every update or big config change
hermes backup	A zip of your Hermes data, including credentials	To move the agent to a new VM, or keep a copy off the VM
hermes update --backup	A full backup, then the update	Every routine update

A safe update routine looks like this:

1. Take a VM snapshot.
2. Run hermes update --backup.
3. Test the agent with one simple task.
4. If it fails, revert to the snapshot. If it works, delete old snapshots after a few days.

To restore on a fresh VM, install Hermes, then run hermes import with the backup zip. The backup holds your API keys, so store it like a password.

Do not delete ~/.hermes/ to fix a broken install. The docs warn against it, because that folder holds all of your agent's state. Revert the snapshot instead.

Do not keep the data on a shared folder

Hermes stores state in an SQLite database in WAL mode. The Docker docs warn that bind mounts across a VM boundary (virtiofs, 9p and drvfs) can silently corrupt it. Keep ~/.hermes/ on the VM's own disk. Do not move it to a hypervisor shared folder to "save space".

Security hardening checklist

• Run as a normal user. Never run the gateway as root.
• Keep approvals on. Leave dangerous-command approval in smart or manual mode. Unattended and cron sessions deny by default.
• Keep ports closed. The API server (port 8642) is off by default. The dashboard (port 9119) runs only when you start it with hermes dashboard --no-open, and it binds to 127.0.0.1. Reach it through an SSH tunnel: ssh -L 9119:localhost:9119 you@vm-address.
• Use allowlists for every chat platform.
• Give the VM no secrets it does not need. Do not copy your SSH keys or cloud credentials into it.
• Consider a Docker terminal backend. Install Docker Engine in the VM, then set terminal.backend: docker. Shell and file tools then run in a container inside the VM. Note that Hermes skips command approval on this backend, because it treats the container as the boundary.

See the Hermes security guide for the full list.

Alternative: Hermes Agent in Docker inside the VM

If you prefer containers, the official image is nousresearch/hermes-agent, for amd64 and arm64. Install Docker in the VM from the Docker Engine docs for Ubuntu. Use this instead of the native install, not alongside it. Both use ~/.hermes, and two gateways must never share one data folder. Then run the first-time setup:

mkdir -p ~/.hermes
docker run -it --rm \
  -e HERMES_UID=$(id -u) -e HERMES_GID=$(id -g) \
  -v ~/.hermes:/opt/data \
  nousresearch/hermes-agent setup

Then start the gateway:

docker run -d \
  --name hermes \
  --restart unless-stopped \
  -e HERMES_UID=$(id -u) -e HERMES_GID=$(id -g) \
  -v ~/.hermes:/opt/data \
  nousresearch/hermes-agent gateway run

Two differences matter. First, hermes update refuses to run in Docker. You update by pulling a new image. Second, the dashboard runs only if you set HERMES_DASHBOARD=1, and inside the container it binds to 0.0.0.0. If you need it, publish it as -p 127.0.0.1:9119:9119 and use an SSH tunnel. If you use browser tools in Docker, add --shm-size=1g.

Troubleshooting

Problem	Fix
hermes: command not found	Run source ~/.bashrc, or check that ~/.local/bin is in your PATH.
Installer exits with no message on minimal Ubuntu	Run sudo apt install libatomic1, then run the script again.
Installer hangs while it downloads a browser	Run bash install.sh --skip-browser, or curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash -s -- --skip-browser. Add browser tools later, as the install docs describe.
"API key not set"	Run hermes model and enter the key again.
Local Ollama model rejected	Raise the model's context to 64,000 tokens or more.
Config errors after an update	Run hermes config check, then hermes config migrate.
Anything else	Run hermes doctor. If it still fails, revert to your snapshot.

FAQ

Is Hermes Agent free?

The agent is open source under the MIT license. You pay for the model you connect, unless you run a local model. Check your provider's pricing page for current rates.

Can I install Hermes Agent with pip?

No. As of October 2026, the platform page lists pip and PyPI installs as unsupported. Use the official install script or the Docker image.

How much RAM does Hermes Agent need?

The official container figure is 1 GB minimum and 2 to 4 GB recommended. Browser tools need at least 2 GB. For a full Ubuntu VM, 4 GB is a comfortable start.

Does Hermes Agent work on Ubuntu 22.04?

It may work, because the docs say most glibc and systemd distributions are likely to work. As of October 2026, I found no official test of 22.04. Use 24.04 to stay on the tested path.

Is a VM safer than running Hermes on my laptop?

Yes. The agent runs commands on whatever machine it lives on. A VM limits that to a disposable system you can snapshot and revert. It is not perfect isolation, so still keep secrets out of the VM.

Can I run Hermes Agent in a VM on an Apple Silicon Mac?

As of October 2026, Hermes lists Linux on aarch64 as supported, so an ARM Ubuntu VM is a valid target. VMware Fusion Pro can run ARM Ubuntu. Hermes also runs natively on macOS, but then it has access to your Mac.

Related guides

• Install OpenClaw in an Ubuntu VM with Docker Compose
• Hermes vs OpenClaw on Virtual Machines: Which Fits Your Setup?
• Containers vs Virtual Machines: When to Use Which
• What Is a Home Lab? How to Start One in 2026
• VMware vs VirtualBox vs Proxmox for a Desktop Lab