Hermes Agent is an always-on AI agent. It learns from your interactions and turns your workflows into reusable skills. You can run it two ways: as a managed service or self-hosted on your VPS with Docker. The managed route saves you setup time. The self-hosted route gives you full control over the models, memory, and tools. This guide walks you through both paths, step by step.
How Do You Set Up a Self-Hosted Hermes Agent?
Self-hosting puts the server, models, and security in your hands. Basic Linux and Docker knowledge helps here. Start with step one below.
Step 1: Prepare Your VPS
Pick a VPS with a Linux distribution. Ubuntu works well for your server. You’ll need root access, plus a connection that stays stable. For hardware, 2 CPU cores and 8 GB of RAM gets the job done. This handles Docker isolation and the gateway process without strain. The Hermes container itself only needs about 1 GB of RAM, or 2–4 GB if you turn on browser automation.
Once you connect over SSH, update your system first:
sudo apt update && sudo apt upgrade -yThis step clears out conflicts before you install Docker. Take a few extra minutes here and create a dedicated user, set proper permissions, and enable key-based login. These small steps protect your server later.
Step 2: Deploy Hermes Agent With Docker
Docker bundles Hermes Agent with everything it needs. No need to install Python or Node.js or set environment variables manually.
If you don’t have a VPS yet, use a ready-made Hermes Agent template. Pick a plan, complete checkout, and the system installs everything for you. During setup, you’ll create a username and password for the web terminal. Once the install finishes, open the Docker Manager, find the Hermes project, and click Open.
If you already run a VPS, deploy Hermes from your hosting panel instead. Go to your VPS settings, change the operating system, and search for Hermes Agent. Please select it, and the panel will install it for you.
If you’re on a different provider, install Docker manually first. Then create a data folder for Hermes:
mkdir -p ~/.hermes
cd ~/.hermes
Run the container:
docker run -it --rm -v ~/.hermes:/opt/data nousresearch/hermes-agent setup
The -v flag connects your local folder to the container’s data path — this is where Hermes keeps your keys, sessions, skills, and memory. Skip it, and you lose all of that on restart.
Related Read: What is Hermes Agent?
Step 3: Run the Setup Wizard
Once the container starts, the setup wizard opens on its own. It gives you two options:
- Quick setup. Covers the provider, model, and messaging. Most users should pick the full setup.
- Full setup. Adds backend selection, behaviour settings, and persona configuration.
Choose Quick setup. You can adjust the rest later. The wizard asks you to:
- Pick an LLM provider — Anthropic, OpenAI, OpenRouter, Nous Portal, or Ollama.
- Enter your API key for that provider.
- Choose a model from the list.
- Connect a messaging platform, like Telegram, Discord, Slack, or WhatsApp. You can skip this step and test through the command line first.
Hermes keeps sensitive data, like your API key, in ~/.hermes/.env. Everything else goes into ~/.hermes/config.yaml.
Step 4: Verify the Setup
Open a chat session. Confirm that Hermes can access your model without any errors.
hermes
You should see a welcome banner with your model, tools, and skills listed. Try a prompt that uses a tool — ask what’s in the current directory, for instance. If Hermes replies and runs the command, you’re set up correctly.
Type /exit to leave the session. Use hermes again to start fresh, or hermes –continue to pick up your last session.
If you run into empty replies or connection errors, the first thing that you should check is the API key. Run hermes setup to fix it. Or run hermes doctor to scan your entire setup for problems.
Step 5: Add More Models and Tools
With the chat confirmed, you’re free to add more providers or hook up additional services.
Run hermes model to add a new provider. It walks you through the same steps as before. Switch between providers mid-session with the /model command.
To connect a messaging channel, run hermes gateway setup and follow the prompts. Once it’s set up, run hermes gateway run to start the bot. Without this command, the channel stays configured but stays quiet.
Hermes also comes with built-in tools: terminal access, web search, file system access, and image generation. Run hermes tools to see the list and switch each one on or off. Note that some tools, like web search, need their own API keys to work.
Step 6: Secure Your Setup
Tirith is the scanner built into Hermes. It checks every terminal command before running it and flags risks like prompt injection or credential theft. It’s on by default. When it flags something, approve or deny it with /approve or /deny.
Control how approvals work by editing ~/.hermes/config.yaml:
approvals:
mode: manual # manual | smart | off
timeout: 60
Manual mode asks before every risky command. Lock down your messaging gateway as well. Off disables checks entirely.
Add your user ID to the allowed list in the same configuration file as the messaging gateway.
gateway:
telegram:
allowed_user_ids:
- 123456789
Add your own ID here. Please follow the same procedure for any other platform you have set up.
Close ports 8642 and 9119 if you only use Hermes through a chat app:
sudo ufw deny 8642
sudo ufw deny 9119
To update Hermes, pull the latest image and swap the container:
docker pull nousresearch/hermes-agent:latest
docker rm -f hermes
docker run -d --name hermes --restart unless-stopped -v
~/.hermes:/opt/data nousresearch/hermes-agent gateway run
Your data stays safe in the mounted folder during updates. Also turn off root SSH login, set up fail2ban, and run a malware scanner on your VPS for extra protection.
How Do You Set Up a Managed Hermes Agent?
A managed Hermes Agent skips the server work. The host prepares the environment, handles updates, and manages backend security. You just pick a model and connect your channels.
Step 1: Choose a Managed Hermes Plan
Log in to your hosting panel and select Hermes from the sidebar. Pick a subscription period. You can also add optional features, like ready-to-use AI credits for models such as Claude, Gemini, or GPT, or web search credits for pulling live data. Skip these if you’d rather connect your own provider key.
Step 2: Pick Your AI Provider
When you set up, you’ll choose how Hermes connects to an AI model. Use the built-in AI credits, or enter your provider’s API key. If you bring your key, you’ll pick the exact model once the app finishes deploying.
Step 3: Open Your Hermes Application
Once deployment’s done, open the app and grab the access key on screen. This is your gateway token — please copy it to a secure location and refrain from sharing it with others.
Step 4: Finish the Initial Setup
Please review your settings in the setup window before proceeding. If you did not select the built-in AI option earlier, please enter your API key now and choose a model. The app sets your password automatically, so you can skip that part. Please confirm your selections to complete the process.
Step 5: Connect a Channel and Test It
Start with a channel; Telegram, WhatsApp, and email all work. Follow the prompts on the screen to authorise it. Once that’s done, send a test message and see if Hermes replies through the model you picked.
Once it’s running, head to the management panel. From there you can switch providers, monitor credit usage, restart the app, view logs, or grab your access key again.
A Few Important Considerations
- Test the CLI before adding channels
Confirm Hermes responds and runs tools before you connect Telegram, Slack, or cron jobs. This makes troubleshooting far easier if something breaks later. - Always mount the data volume
Skip the -v flag when running the container, and you lose your memory, skills, and settings on every restart. - Keep your API keys current.
Expired or wrong keys are the most common reason Hermes stops responding. Run hermes setup to refresh them. - Set the gateway allowlist
Without allowed_user_ids in your config, anyone who finds your bot can send it commands. - Sandbox the terminal on a VPS
By default, Hermes runs commands directly on your server. Switch to hermes config set terminal.backend docker so commands stay isolated from the rest of your system. - Back up your Hermes folder regularly
The ~/.hermes directory holds your models, memory, skills, and sessions. Managed plans back up automatically once a day; self-hosted setups need a manual routine.
