The Install Guide
Install Your Own AI Agent.
Step by Step.
Eleven steps. Copy-paste commands. All the gotchas I learned the hard way. If you read the story, this is the "how."
Before You Start: Gather Your Keys
Some steps in this walkthrough need API keys or tokens. Getting them before you start is way easier than stopping mid-install to go sign up for stuff. Here's everything you'll need:
| Service | What You Need | Link |
|---|---|---|
| OpenRouter | API key (free tier works) | openrouter.ai |
| Ollama Cloud | API key (paid, ~$20/mo — optional alternative to OpenRouter) | ollama.com |
| Telegram | Bot token (via @BotFather) | t.me/BotFather |
| Composio | Account (optional — connects Gmail, GitHub, Reddit, etc.) | composio.dev |
Tip: You don't need all of these on day one. At minimum, you need one model provider key (OpenRouter or Ollama Cloud) and a Telegram bot token. Composio can wait.
What You Need
Before you touch a terminal, make sure you've got the basics:
- A computer running Linux, macOS, or WSL2 (Windows Subsystem for Linux)
- An internet connection — your agent lives online
- About 30 minutes — less if you've done this kind of thing before
Surface laptop users: I'm going to be real with you. WSL2 works, but it's a layer on top of Windows that was never designed for this. You'll spend more time debugging WSL than using your agent. Wipe it, install Ubuntu, and start clean. You'll thank me later.
NAS users (same as me — Ugreen, running Linux): You're already in good shape. This stuff was born on Linux. It'll feel like home.
Install Hermes
Here's the one-liner that does all the heavy lifting:
curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash What this does: clones the repo, sets up a Python virtual environment, installs all the dependencies. Voodoo blackmagic stuff happening behind the curtain.
After it finishes, run:
hermes doctor This checks your setup and tells you what's working and what's not.
Warning: This installs the latest version from the main branch. If something broke in the last commit, you're the one who finds it. If things go sideways, check the docs or the subreddit.
Run the Setup Wizard
hermes setup This walks you through the basics: model provider, API keys, terminal settings. It creates your config.yaml and .env files — the two files that control everything.
Don't skip this. I know you want to skip this. You'll create the config manually and miss a setting and spend an hour wondering why nothing works.
Tip: If you gathered your keys from the table above, you're already set. If not, go get them now, then run hermes setup.
Choose Your Brain (Model Provider)
Your agent needs a model to think. This is the "brain" — the thing that actually reads your messages and writes back. You've got three options:
Local
Ollama (self-hosted)
Free, needs your own GPU
Not an option if your GPU is busy.
CRITICAL: ollama and ollama-cloud are NOT the same provider. Different API endpoints. Different auth. Different everything. Pick the wrong one and you'll get HTTP 404 on every request. This is the #1 support question on r/hermesagent. Get this right the first time.
Connect Telegram
This is how you actually talk to your agent. Through Telegram, like texting a friend.
- Open Telegram, message @BotFather
- Send
/newbot, follow the prompts - You'll get a bot token — long string of letters and numbers
- Add it to your
.envfile:
TELEGRAM_BOT_TOKEN=your_token_here - Start the gateway:
hermes gateway start - Verify it's connected:
grep "telegram connected" ~/.hermes/logs/gateway.log CRITICAL: Set TELEGRAM_ALLOWED_USERS=your_chat_id in your .env. Without this, your bot connects to Telegram but ignores every message. The log says "connected." Nothing works. This is the #2 support question. Set this. Do it now.
Tip: To find your chat_id, message your bot, then open this URL in a browser (replace <YOUR_TOKEN> with your actual token):
https://api.telegram.org/bot<YOUR_TOKEN>/getUpdates First Conversation
hermes That's it. Type something. Anything.
Try: "Who are you?"
See if it talks back. If nothing happens:
cat ~/.hermes/logs/gateway.log The first conversation is always awkward. Like a new employee on day one. Give it a minute. Send a few messages. It'll find its footing.
Set Up Persistence
Right now, if you close your terminal or reboot, the gateway dies. Here's how to make it survive:
hermes gateway install
systemctl --user start hermes-gateway This installs the gateway as a systemd service. It'll start automatically on boot.
SSH users: Also run:
sudo loginctl enable-linger $USER Without this, systemd kills your user services when you disconnect. Your gateway dies every time you close your SSH session.
WSL2 users: Make sure systemd=true is set in /etc/wsl.conf. Without it, systemd doesn't start and none of the above works.
Connect Composio
Your agent can think. But without Composio, it can't do much. It's like having a smart employee with no phone, no email, and no internet.
- Go to composio.dev and create an account
- Connect the apps you want: Gmail, GitHub, Reddit, Google Drive, Slack, whatever
- Add the Composio MCP server to your Hermes config
Why bother? Reddit blocks direct HTTP requests. GitHub has rate limits. Composio handles all of that — auth, rate limiting, API changes.
Without Composio, your agent is blind to half the internet. With it, it can see everything.
Add Skills
See what's available:
hermes skills browse Install one:
hermes skills install <skill-name> Skills are like training manuals for your agent. They teach it how to do specific things — manage GitHub, post to Spotify, interact with your calendar.
Tip: Start with the built-in skills. Get comfortable. Add more later. You wouldn't hand a new hire the entire company handbook on day one.
Set Up Cron Jobs
Want your agent to do things on a schedule? Daily briefings, weekly reports, monitoring — cron jobs handle that.
hermes cron create "0 8 * * *" That example runs at 8 AM every day. You define what it does when you create the job.
Warning: Free OpenRouter models have tight rate limits. Cron jobs will hit HTTP 429. Use Ollama Cloud for anything scheduled.
Updates (The Inevitable)
hermes update CRITICAL: hermes update RESTARTS THE GATEWAY AUTOMATICALLY. Your session WILL DIE. If you run this from inside the agent, you're pulling the rug out from under yourself. Use a separate terminal. Always.
After updating:
- Check
config.yaml— model settings sometimes reset to defaults - Check custom files for merge conflicts
Tip: Before you update, back up your config:
cp ~/.hermes/config.yaml ~/config-backup.yaml Common Pitfalls
I've seen these come up over and over. Read this section. It'll save you a trip to the subreddit.
1. NEVER restart the gateway from inside the agent. It kills your own session. Use a separate shell. Every time.
2. ollama ≠ ollama-cloud. Different providers. Wrong one in your config = HTTP 404 on every request. Check your config. Check it again.
3. TELEGRAM_ALLOWED_USERS must be set. Without it, your bot connects to Telegram but ignores everyone. The log says "connected." Nothing works.
4. Free OpenRouter models have rate limits. Cron jobs will hit HTTP 429. Use Ollama Cloud for scheduled tasks.
5. sudo pip install will fail on locked-down systems. Use the venv Python path instead.
6. Reddit blocks direct HTTP. Always use Composio tools for Reddit.
7. Memory is only 2,200 characters. Use external storage for anything important.
8. hermes update restarts the gateway. Always warn yourself before running it. Separate terminal.
9. Satellite instances need their own .env keys. They don't inherit from the main instance.
10. Gateway shows "telegram connected" even with no API key. Check your provider keys separately.
That's It.
You've got a working AI agent running on your own hardware. It talks through Telegram, it can browse the internet, check your email, manage your GitHub — whatever you set it up to do.
Fair warning: you will break things. That's part of the process. The guys on the subreddit have seen it all. Don't be afraid to ask.
Pro tip of the day: Before you ask the internet, ask your agent. It might just know. And if it doesn't, it'll find out. That's the whole point.
One last thing — don't use this like you would Google. It will waste your tokens. Save the "what time does the parts store open" questions for the search engines. This is more than that. Go build things, and see you on Thursday's call.
This page is part of the Wet Dog Drones site.
Questions? Find me in Drone Mapping Answers.