Run Hermes Agent safely on Mac in a Linux ARM VM

Run Hermes Agent safely on Mac by giving it a dedicated Linux ARM VM instead of installing it directly in your host macOS account. Kyvenza creates the arm64 guest and keeps Hermes data, tools, sessions, credentials, and package changes inside that guest unless you deliberately share folders back to the Mac.

This guide uses Ubuntu ARM as the example because it is a practical default for a Linux server-style Hermes deployment. Debian ARM and Fedora ARM are also supported Kyvenza guest choices; use the equivalent package commands for those distributions.

Why run Hermes Agent safely on Mac in Kyvenza

Kyvenza is a good fit when you want a Hermes Agent VM that behaves like a small Linux machine on the Apple Silicon Mac you already use.

Use this workflow when:

• You want to test Hermes without giving it your host home directory, SSH keys, browser profile, or work files.
• You want a clean Linux environment for Hermes memory, skills, sessions, gateway config, and provider credentials.
• You plan to connect Telegram, Discord, Slack, or another messaging gateway and want the service isolated from your main Mac account.
• You are comparing agent behavior across profiles and want one VM per experiment.
• You prefer a full guest OS over running everything inside the shared Docker Desktop environment on macOS.

This is still a local setup. Hermes runs only while your Mac is awake and the Kyvenza VM is running. If you need unattended 24/7 service while your Mac is off, use a VPS or another always-on machine.

Requirements

On the Mac host:

• An Apple Silicon Mac running macOS 14.0 Sonoma or later.
• Kyvenza installed and past first-run onboarding. See Install Kyvenza and System requirements.
• Enough disk space for the Linux guest, Hermes data under ~/.hermes, optional Docker images, browser tooling, logs, and workspace files.
• A Kyvenza Free or Pro entitlement. The Free tier allows up to three VMs; Pro removes that VM count limit. See Licensing.

Inside the Linux guest:

• Ubuntu ARM, Debian ARM, or Fedora ARM installed from an arm64 installer.
• Internet access from the guest.
• git available before running the Hermes git-based installer.
• A model provider account or endpoint you plan to configure with Hermes.
• Docker Engine only if you want the optional container path or Docker terminal backend.

Hermes Agent's official docs describe the one-line installer for Linux, macOS, and WSL2, and note that the installer handles uv, Python 3.11, Node.js, ripgrep, and ffmpeg after Git is available. Read the official Hermes installation guide, quickstart, Docker guide, configuration guide, messaging gateway guide, and security guide before exposing real accounts.

Create the Linux ARM VM in Kyvenza

1. Open Kyvenza.
2. Click + in the toolbar to start the VM assistant.
3. Choose Linux.
4. Select Ubuntu unless you specifically want Debian or Fedora.
5. Name the VM something obvious, such as hermes-ubuntu.
6. Start with 4 vCPUs, 4096 MB of memory, and 64 GB of disk. Increase memory and disk if you plan to run Docker, browser automation, or long-lived workspaces.
7. Keep the storage path on a disk with enough free space.
8. Skip shared folders during the first install. Add only narrow, intentional shares later.
9. Review the configuration and click Create VM.

Kyvenza downloads the latest official ARM64 installer for the selected Linux distribution and mounts it on the first boot. Install Linux normally in the VM console, shut the guest down when the installer finishes, then start it again. If Kyvenza does not automatically detect that installation is complete, use the Linux installation completion control in the VM detail view before the next boot.

For the general VM workflow, see Create your first VM, Managing VMs, and Importing images.

Install Hermes Agent directly in the Linux VM

After the Linux guest boots into the installed system, open a terminal inside the VM.

For Ubuntu or Debian, install the small set of tools you need before the Hermes installer:

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

Run the official Hermes installer:

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

Reload your shell so the hermes command is available:

source ~/.bashrc

Run the setup wizard:

hermes setup

Use the setup flow to choose your model provider, configure credentials, and decide which tools should be enabled. Then verify the install:

hermes --version
hermes doctor

Start with a normal CLI conversation before you add a gateway, cron job, Docker backend, or messaging platform:

hermes

If the basic chat path works, configure the messaging gateway:

hermes gateway setup

For a Linux user service inside the VM:

hermes gateway install
hermes gateway start
hermes gateway status
journalctl --user -u hermes-gateway -f

Use a user service for a desktop-style Kyvenza VM. Use a system service only if you understand the service account, boot, and credential implications inside the guest.

Optional: run Hermes Agent in Docker

Hermes has two Docker-related modes:

• Run Hermes itself inside a container.
• Run Hermes normally, but configure the terminal backend so agent commands execute inside a Docker sandbox.

Inside a Kyvenza Linux VM, either mode stays inside the guest. Docker adds another boundary inside the VM; it does not replace the VM boundary.

To run Hermes itself in Docker, first install Docker in the Linux guest and verify it:

docker --version

Create the Hermes data directory and run the setup wizard in the official container:

mkdir -p ~/.hermes
docker run -it --rm \
  -v ~/.hermes:/opt/data \
  nousresearch/hermes-agent setup

After setup, run the gateway container in the background:

docker run -d \
  --name hermes \
  --restart unless-stopped \
  -v ~/.hermes:/opt/data \
  nousresearch/hermes-agent gateway run

Hermes documents port 8642 for the optional API server and health endpoint, and port 9119 for the optional dashboard. Do not publish those ports beyond the VM unless you have configured authentication and understand the risk of exposing an agent gateway.

Optional: use Docker as the terminal backend

If you installed Hermes directly in the guest, you can still make Hermes run terminal commands inside a Docker sandbox. This is useful when you want Hermes to keep its gateway and config in the guest account while putting command execution in a separate container.

First confirm Docker works:

docker version

Then configure the terminal backend from Hermes:

hermes config edit

Use a minimal starting point:

terminal:
  backend: docker
  docker_forward_env: []
  docker_mount_cwd_to_workspace: false

Keep docker_forward_env empty until a specific task needs a specific token. Anything forwarded to the Docker backend can be read by code running in that sandbox.

If the Docker backend causes problems, return to the local backend while you debug:

hermes config set terminal.backend local
hermes doctor

Harden the Hermes Agent VM

A Linux ARM VM separates Hermes from your Mac host. You still need to configure Hermes carefully.

Before connecting real accounts or letting Hermes handle untrusted messages:

• Keep Kyvenza shared folders off by default. Do not share ~/.ssh, browser profiles, password-manager exports, or client repositories unless that is the specific task.
• Use Hermes allowlists or DM pairing for messaging gateways. Do not set GATEWAY_ALLOW_ALL_USERS=true for a bot with terminal access.
• Keep dangerous command approvals enabled. Avoid --yolo, /yolo, or approvals.mode: off unless the VM is disposable and the task is tightly scoped.
• Prefer the Docker terminal backend for higher-risk command execution inside the guest.
• Store provider keys and platform tokens inside the guest, not on the host.
• Use one Kyvenza VM per Hermes profile when you want clean separation between personal, research, and work contexts.
• Run hermes doctor after changing providers, tools, terminal backends, gateway auth, or messaging platforms.

If you later decide Hermes should work on host files, add the narrowest possible shared folder and treat that folder as intentionally exposed to the agent.

What Kyvenza does not support

Kyvenza runs native arm64 guests on Apple Silicon. It does not emulate Intel systems and it does not turn a local VM into an always-on server.

Current limits to keep in mind:

• Windows on ARM is not supported.
• x86_64 Linux images are not supported.
• Intel Macs are not supported.
• Nested virtualization is not supported.
• GPU passthrough is not supported.
• Kyvenza uses its bundled Lume backend and ignores a system-installed Lume.
• The VM is local to your Mac; if the Mac sleeps, shuts down, or loses network access, Hermes inside the VM is affected.

How it compares

Running Hermes directly on your Mac is the shortest setup path, but it gives Hermes the same filesystem reach as your host user. That may be fine for a trusted personal assistant. It is a poor default for testing new skills, broad tool access, or messaging gateways connected to outside users.

Docker on macOS is useful, but it belongs to your host development environment. A Kyvenza Linux ARM VM gives Hermes a full guest OS with its own package state, service manager, filesystem, and credential store. You can still run Docker inside the VM for Hermes container deployment or terminal sandboxing.

A VPS or dedicated machine is better when Hermes must stay online while your Mac is asleep or off. Kyvenza is the local option: good for evaluation, agent development, gateway testing, and isolated personal deployments on the Mac you already have.

Troubleshooting

The VM boots back into the Linux installer

Shut the VM down and confirm the Linux installer is marked complete in the Kyvenza VM detail view. If the installer ISO is still mounted, the guest may keep returning to the installer.

hermes is not found after install

Reload the shell and confirm ~/.local/bin is on PATH:

source ~/.bashrc
echo "$PATH"
which hermes

If the command still is not found, rerun the installer output steps carefully and check the official installation troubleshooting section.

The installer fails before setup

Confirm Git and network access inside the guest:

git --version
curl -I https://github.com

On Ubuntu or Debian, reinstall the basics:

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

Hermes says an API key is missing

Run the model setup again:

hermes model
hermes doctor

If you are using Docker, make sure the container is using the same ~/.hermes data directory you configured during setup.

The gateway does not start

Check Hermes first:

hermes doctor
hermes gateway status
journalctl --user -u hermes-gateway -n 100

If you are running Hermes in Docker:

docker ps
docker logs --tail=100 hermes

Docker backend commands fail immediately

Check Docker and then return Hermes to the local backend while you debug:

docker version
hermes config set terminal.backend local
hermes doctor

Kyvenza reports a VM or backend error

Open Diagnostics & Troubleshooting and review the bundled Lume status, recent VM lifecycle events, and storage free space. Pro users can export a diagnostics bundle for support.

Next steps

• Download Kyvenza from kyvenza.com.
• Review System requirements before creating larger Hermes VMs.
• Read the official Hermes security guide before connecting public channels or enabling broad tool access.
• If you are also evaluating OpenClaw, compare this workflow with Run OpenClaw safely on Mac in a Linux ARM VM.
• If you need more than three Kyvenza VMs for separate Hermes profiles, compare Free and Pro on Kyvenza pricing.