Install Hermes AI Agent — Free Step-by-Step Guide for Mac Mini & VPS

Run the Hermes install script

Open Terminal and paste the one-liner — it installs Hermes plus a Python 3.11+ runtime if you don't already have one:

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

Verify the binary is on your PATH: hermes --version. If the command isn't found, open a new terminal window (the installer updates your shell rc file).

Run the setup wizard

This walks you through picking an LLM provider (Claude, OpenAI, Nous Portal, OpenRouter, or a custom endpoint) and creating the gateway daemon so Hermes starts on reboot:

hermes setup

Want the one-click flow with Nous Portal as the model backend? Use hermes setup --portal instead — it handles the API key and per-skill model routing for you.

Choose your model + tools

The wizard prompts for these, but you can re-run them anytime if you change your mind:

hermes model
hermes tools

For Malaysian SMEs we usually pick Claude (Anthropic) for skill quality, or OpenRouter if you want to A/B between models per skill. For the cheapest pay-as-you-go, point Hermes at a self-hosted Ollama model — Hermes treats it as a custom endpoint.

Connect a messenger

The gateway is what lets you DM Hermes from Telegram / WhatsApp / Slack / Discord / Signal:

hermes gateway setup
hermes gateway start

The setup command is interactive — it asks which messenger, then walks you through pairing. For WhatsApp on MY, use a dedicated +60 number, not your primary personal line — WhatsApp may flag a new linked device on your main account.

Pick a sandbox backend for sub-agents

Hermes spawns isolated sub-agents for parallel work. The sandbox backend decides where they run. The hermes setup wizard will ask — Docker is the right default for most SMEs (fast, well-understood, easy to wipe).

The README lists six backends: local (no isolation — only for trusted scripts), docker, ssh (run sub-agents on a separate box), singularity (HPC-style containerisation), modal (serverless, pay-per-execution), and daytona. To change the backend later, re-run hermes setup or check the upstream docs for the current hermes config set key — Nous Research has been iterating on the config schema, so we'd rather you read the canonical reference than copy a stale key from this guide.

Run the doctor and lock down access

Confirm everything is healthy before opening the gateway to your phone number:

hermes doctor

The doctor checks Python version, daemon status, channel connection, sandbox backend, and model auth. Fix anything flagged before continuing. Then add yourself to the messenger's DM allowlist via the gateway config — see the upstream docs for the exact key, since the format may shift between Hermes versions.

Configure for 24/7 headless operation

System Settings → Battery / Energy → uncheck "Put hard disks to sleep when possible" and set "Prevent automatic sleeping when the display is off" to ON. Enable FileVault (System Settings → Privacy & Security) and turn on the macOS firewall. For remote access into the Mac from outside your LAN, install Tailscale and use tailscale serve — don't port-forward Hermes directly on your router.

Send the first test message

Open the messenger you connected and send your Hermes a greeting (e.g. "Hello, what can you do?"). If you get a reply within a few seconds, you're live. To keep the scheduler running across reboots, the setup wizard should have already installed the launchd daemon — confirm with hermes doctor after a reboot.

Provision the VPS

Minimum: 2 vCPU, 4 GB RAM, 20 GB SSD. Region: Singapore (ap-southeast-1 on AWS, SGP1 on DO). SSH in as a non-root user with sudo, and make sure the box is fully updated:

sudo apt update && sudo apt upgrade -y

Install Python 3.11+ and Docker

Ubuntu 24.04 ships Python 3.12 out of the box — fine. On 22.04 you'll want to add the deadsnakes PPA or use pyenv. Install Docker too, since it's the recommended sandbox backend:

sudo apt install -y python3 python3-venv python3-pip
curl -fsSL https://get.docker.com | sudo bash
sudo usermod -aG docker $USER
newgrp docker

Confirm Python: python3 --version. Docker: docker ps (should run without sudo after the group change).

Run the Hermes install script

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

Open a fresh shell after install so the PATH update takes effect, then verify: hermes --version.

Run the setup wizard

hermes setup

The wizard handles model provider selection, tool toggles, and (on Linux) the systemd user service that keeps the gateway alive across reboots. For Nous Portal as the model backend in one click: hermes setup --portal.

Connect a messenger

hermes gateway setup
hermes gateway start

On a headless VPS the QR / pairing code renders in the terminal as ASCII — scan or paste it from your phone. For WhatsApp on MY, use a dedicated +60 number; for Telegram, create a bot via @BotFather and paste the token when prompted.

Pick the Docker sandbox

When the hermes setup wizard asks for a sandbox backend, pick Docker. On a VPS, Docker is almost always the right call — it gives you per-sub-agent filesystem isolation without the cost of a separate machine.

If you need to change it later, re-run hermes setup or check the upstream docs for the current hermes config set key. Alternatives: modal if you want serverless and don't mind metered billing; ssh if you have a separate sandbox host.

Verify with hermes doctor

hermes doctor

Should report green on Python version, daemon, channel, sandbox, and model auth. Anything red? Fix it before sending real traffic. journalctl --user -u hermes-gateway -n 200 --no-pager gives the underlying logs if the doctor isn't specific enough.

Lock down the gateway + send a test message

Keep the Hermes gateway on loopback (127.0.0.1) — don't bind it to the public internet. If you need access from your laptop, reach it via SSH tunnel or Tailscale Serve:

ssh -L 8000:127.0.0.1:8000 user@your-vps-ip

Add yourself to the messenger's DM allowlist (the exact config key is in the upstream docs and may shift between versions; hermes config set is the surface). Then DM "Hello" from the messenger — if you get a reply, you're live.