Self-hosted AI agent on Linux. Talks to you on Telegram, runs commands, manages servers, connects to tools via MCP. This is the fast path. Run the blocks top to bottom. Replace youruser with your Linux username everywhere.

Pasted image 20260528175133

Hermes is the agent. You plug a model into it (OpenAI, Gemini, local endpoint). Keep that straight.

1. Install#

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

Note the path (usually ~/.local/bin/hermes). You need it for the service.

2. Setup wizard#

hermes setup

Pick your model provider and API key. Terminal: local. Skip TTS.

3. Telegram bot#

In Telegram: message @BotFather, /newbot, copy the token. Message @userinfobot, copy your numeric ID.

cat >> ~/.hermes/.env <<'EOF'
TELEGRAM_BOT_TOKEN=your_bot_token
TELEGRAM_ALLOWED_USERS=your_numeric_id
TELEGRAM_HOME_CHANNEL=your_numeric_id
EOF

4. Run as a system service#

sudo $(which hermes) gateway install --system --run-as-user youruser
sudo $(which hermes) gateway start --system
sudo systemctl status hermes-gateway

Message your bot “hi” on Telegram. It should reply.

5. Voice (Groq STT)#

Key from console.groq.com.

cat >> ~/.hermes/.env <<'EOF'
GROQ_API_KEY=your_groq_key
STT_GROQ_MODEL=whisper-large-v3-turbo
EOF
hermes config set stt.provider groq
sudo systemctl restart hermes-gateway

6. Web search (Tavily)#

Free key from app.tavily.com.

echo 'TAVILY_API_KEY=your_tavily_key' >> ~/.hermes/.env
sudo systemctl restart hermes-gateway

7. GitHub#

sudo apt update && sudo apt install -y curl
curl -fsSL https://cli.github.com/packages/githubcli-archive-keyring.gpg | sudo dd of=/usr/share/keyrings/githubcli-archive-keyring.gpg
sudo chmod go+r /usr/share/keyrings/githubcli-archive-keyring.gpg
echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/githubcli-archive-keyring.gpg] https://cli.github.com/packages stable main" | sudo tee /etc/apt/sources.list.d/github-cli.list > /dev/null
sudo apt update && sudo apt install -y gh
gh auth login

Pick GitHub.com, HTTPS, browser login. Open github.com/login/device, paste the code. Then:

echo "GITHUB_TOKEN=$(gh auth token)" >> ~/.hermes/.env
sudo systemctl restart hermes-gateway

8. Persona (SOUL.md)#

cat > ~/.hermes/SOUL.md <<'EOF'
# Identity
You are a pragmatic senior engineer. Talk to me as a technical peer.

# Style
- Lead with the answer or command. No preamble.
- Terse by default. Code first, short explanation after.
- No em-dashes. No emojis. Plain, direct language.
- Say when something is a bad idea and give the better option.
- State uncertainty instead of guessing. Verify with tools.

# Defaults
- On ambiguity, assume the reasonable thing, state it, proceed.
- Multi-step work: brief plan, then execute end to end.
EOF
sudo systemctl restart hermes-gateway

9. Fallback model (Gemini)#

Free key from aistudio.google.com.

echo 'GOOGLE_API_KEY=your_aistudio_key' >> ~/.hermes/.env
hermes fallback add

Pick Gemini, API key, gemini-2.5-flash. Check: hermes fallback list.

10. MCP servers#

cat >> ~/.hermes/.env <<'EOF'
CONTEXT7_API_KEY=your_context7_key
N8N_MCP_TOKEN=your_n8n_token
EOF
nano ~/.hermes/config.yaml

Add under mcp_servers: (2-space indent, spaces only):

mcp_servers:
  github:
    command: "npx"
    args: ["-y", "@modelcontextprotocol/server-github"]
    env:
      GITHUB_PERSONAL_ACCESS_TOKEN: "${GITHUB_TOKEN}"

  context7:
    url: "https://mcp.context7.com/mcp"
    headers:
      Authorization: "Bearer ${CONTEXT7_API_KEY}"

  n8n:
    url: "https://your-n8n-domain/mcp-server/http"
    headers:
      Authorization: "Bearer ${N8N_MCP_TOKEN}"

Validate and restart:

python3 -c "import yaml; yaml.safe_load(open('$HOME/.hermes/config.yaml'))" && echo valid
sudo systemctl restart hermes-gateway
hermes mcp list
hermes mcp test github

Servers with url: are HTTP. Servers with command: are spawned by Hermes. Use what the server documents.

11. Fix the auto-update password problem#

hermes update restarts the service, which needs passwordless sudo. Without this it prompts for a password and the nightly cron breaks. Check your systemctl path first:

which systemctl

Use that exact path in the rule. If it says /usr/bin/systemctl but your rule says /bin/systemctl, sudo ignores it and asks for a password. This is the most common mistake.

sudo tee /etc/sudoers.d/hermes-gateway > /dev/null <<'EOF'
youruser ALL=(root) NOPASSWD: /usr/bin/systemctl restart hermes-gateway, /usr/bin/systemctl start hermes-gateway, /usr/bin/systemctl stop hermes-gateway, /usr/bin/systemctl reset-failed hermes-gateway, /usr/bin/systemctl is-active hermes-gateway, /usr/bin/systemctl status hermes-gateway
EOF
sudo chmod 440 /etc/sudoers.d/hermes-gateway
sudo visudo -c

Test, should NOT ask for a password:

sudo systemctl restart hermes-gateway
hermes update

12. Nightly auto-update cron#

sudo apt install -y cron
sudo systemctl enable --now cron
sudo timedatectl set-timezone Your/Timezone
crontab -e

Add this line (runs 3:30 AM):

30 3 * * * $HOME/.local/bin/hermes update --check >/dev/null 2>&1 && $HOME/.local/bin/hermes update >> $HOME/.hermes/logs/auto-update.log 2>&1; sleep 30; /usr/bin/systemctl is-active hermes-gateway >> $HOME/.hermes/logs/auto-update.log 2>&1

13. Validate#

sudo systemctl is-active hermes-gateway
hermes -z "say hi in 3 words"
hermes mcp list
hermes doctor

From Telegram: send text, send a voice note, ask “list files in /tmp”, ask “list my GitHub issues”. If all work, done.

Notes#

Lock TELEGRAM_ALLOWED_USERS to just your ID. Anyone on that list can run commands through the agent.

Use a dedicated Linux user and a dedicated VM. The agent gets shell access, treat the box as disposable.

For zero approval prompts on a trusted box, set in config.yaml:

approvals:
  mode: auto
  cron_mode: allow

This lets the agent run anything without asking. Right for a single-user locked-down VM, wrong if others can reach the bot.

Manage the service#

sudo systemctl restart hermes-gateway
sudo systemctl status hermes-gateway
sudo journalctl -u hermes-gateway -f

That is the whole setup. The real value comes after: tell the agent to save useful multi-step solutions as skills, and tell it facts about your environment so it learns you over time.