Self-host Hermes Agent on a Linux VPS: step by step

What Hermes Agent is

Hermes Agent is an open-source agent from Nous Research. It runs in a terminal, keeps memory and skills, and can serve the same agent through messaging platforms such as Telegram, Discord and Slack from one gateway. It can run commands and use tools, so plan its permissions carefully.

As with other agents, the model normally runs at a provider, so a small server is enough for the agent itself. Browser and command-line tools add load, so our application page suggests planning for about 4 GB. Model providers bill separately.

free -h
nproc
df -h /

Create a dedicated user and install

Install under a normal user with no sudo rights. The installer needs Git, curl, tar and a SHA-256 tool, and installs the command into ~/.local/bin. Download the script and read it before you run it.

sudo apt install git curl tar libatomic1
sudo adduser --disabled-password --gecos "" hermes
sudo -iu hermes

sudo dnf install git curl tar libatomic
sudo useradd -m hermes
sudo -iu hermes

curl -fsSL https://hermes-agent.nousresearch.com/install.sh -o hermes-install.sh
less hermes-install.sh
bash hermes-install.sh
source ~/.bashrc
hermes doctor

Choose a model and tools

Run the setup commands to choose a provider and model and to switch tools on or off. Use a key made for this agent alone. Configuration lives under ~/.hermes/, so back that folder up and keep it private. Turn on only the tools the job needs.

hermes model
hermes tools
ls -la ~/.hermes/
chmod 700 ~/.hermes

hermes

Contain what the agent can run

An agent that can run commands needs a boundary. Hermes has command approval, authorisation and container isolation features, and you should read the security section of its documentation before enabling command tools on a server. A safe starting point is to leave approvals on and to run command tools in a container or a separate low-privilege environment, so that a bad command cannot reach your real data. Never give the agent root.

Keep the server itself small and single-purpose. Do not run it on a machine that holds other people's data, production databases or SSH keys to other servers.

Connect a messaging platform

The gateway connects Hermes to a chat service. The setup command asks which platform to use and for the bot credentials, which you create in that platform's developer settings. Use a bot used only for this agent.

hermes gateway setup

Decide who may use it

By default you should assume nobody except named people. Set an allowlist of user IDs for each platform, or use direct-message pairing, where an unknown person receives a one-time code that you approve. Never enable "allow all users" on a server.

TELEGRAM_ALLOWED_USERS=123456789,987654321
DISCORD_ALLOWED_USERS=123456789012345678

hermes pairing list
hermes pairing approve telegram CODE
hermes pairing revoke telegram 123456789

Run the gateway at boot

On a VPS you want a system service that starts at boot and runs as the hermes user. The command installs a unit that shuts down cleanly and restarts after failures. Do not add custom stop hooks that kill processes, because they also run on restarts. If you prefer a user service, enable linger so it survives logout.

sudo /home/hermes/.local/bin/hermes gateway install --system --run-as-user hermes
sudo /home/hermes/.local/bin/hermes gateway start --system
sudo /home/hermes/.local/bin/hermes gateway status --system

sudo loginctl enable-linger hermes
hermes gateway install
hermes gateway start

Update, back up and watch costs

Update with the project's own update command, after reading its release notes. Back up ~/.hermes/ with the backup tools from the earlier guides. Check your provider's usage page regularly: a looping task or a busy chat can spend your budget quickly, so set a limit with the provider as well as in the agent.

hermes update
hermes doctor
tar czf ~/hermes-backup-$(date +%F).tar.gz -C ~ .hermes