Set Up Hermes Agent with DeepSeek
Run a self-improving AI agent 24/7 for pocket change. Install Hermes Agent, point it at DeepSeek, and talk to it from your phone over Telegram.
Why Hermes Agent + DeepSeek?
Hermes Agent by Nous Research is an open-source agent that keeps memory, writes its own reusable skills, runs scheduled jobs and answers you on chat apps. Because it runs all day and re-sends a long system prompt, memory and skill context on every turn, most of what it spends goes on input tokens, and most of those repeat from turn to turn.
DeepSeek caches repeated prompt prefixes automatically and bills cache hits at a tiny fraction of the normal input price. For a long-running agent that combination of a large stable context and cheap cache hits matters most. A busy personal agent can cost less per month than one lunch.
deepseek-flash (off-peak; $0.006 peak)Monthly Agent Cost Estimator
Drag the sliders to match your agent's workload.
DeepSeek rates from the official pricing page (November 2026). Frontier rows use representative list prices for comparison: mid-tier frontier at $3 input / $0.30 cached / $15 output per 1M, and flagship frontier at $5 / $0.50 / $25. Real bills vary with model choice, prompt structure and tool usage, so treat these numbers as estimates.
The Setup Roadmap
Three steps, about 30 minutes in total. Each step has a quick summary. Click its button to reveal the full, detailed guide.
- Docker: create
~/.hermes, run the one-timesetupwizard in a throwaway container, then startgateway runwith--restart unless-stopped. - macOS:
brew install uv git ripgrep ffmpeg node, run the official install script, then keep the gateway alive with alaunchdagent. - Windows: install Git and uv with WinGet, run the PowerShell installer, and start the gateway from a terminal or Task Scheduler.
- Check everything with
hermes doctor.
mkdir -p ~/.hermes
docker run -it --rm -v ~/.hermes:/opt/data nousresearch/hermes-agent setupBefore you start
Hermes Agent has two parts. The CLI (hermes) is the interactive chat and config tool. The gateway (hermes gateway) is a background daemon that runs scheduled jobs and connects your agent to Telegram, Discord and other chat apps. For a 24/7 agent, the gateway is the part that must stay up.
- All state (keys,
config.yaml, memories, skills, sessions, cron jobs) lives in~/.hermes. Back up that folder and you've backed up your agent. - API keys go in
~/.hermes/.env, and model and behaviour settings go in~/.hermes/config.yaml. - Have a DeepSeek API key ready. When the setup wizard asks for a provider, you can choose DeepSeek straight away (see step 2).
Choose your platform
Docker is the simplest way to run Hermes 24/7 on a home server, a NAS, a mini PC or a cheap VPS. The official image is nousresearch/hermes-agent, and everything persistent lives in one mounted folder, so upgrades are a pull and a restart.
-
Create the data directory
mkdir -p ~/.hermes -
Run the one-time setup wizard
This starts a throwaway container that writes
.envandconfig.yamlinto your data folder. Choose DeepSeek as the provider when asked, or skip it and configure it later.docker run -it --rm \ -v ~/.hermes:/opt/data \ nousresearch/hermes-agent setup -
Start the gateway as a long-running container
docker run -d \ --name hermes \ --restart unless-stopped \ -v ~/.hermes:/opt/data \ nousresearch/hermes-agent gateway runChat platforms like Telegram connect outbound, so you don't need to publish any ports. Add
-p 8642:8642only if you want Hermes' OpenAI-compatible API server, and never expose it on an internet-facing machine without a key and firewall. -
Chat with it or check on it
# Interactive CLI session against the same data docker run -it --rm -v ~/.hermes:/opt/data nousresearch/hermes-agent # Or exec into the running container docker exec -it hermes /opt/hermes/.venv/bin/hermes # Logs docker logs -f hermes
Docker Compose version
Save this as docker-compose.yml, then run docker compose up -d:
services:
hermes:
image: nousresearch/hermes-agent:latest
container_name: hermes
restart: unless-stopped
command: gateway run
volumes:
- ~/.hermes:/opt/data
# Optional web dashboard on http://localhost:9119
# ports:
# - "127.0.0.1:9119:9119"
# environment:
# - HERMES_DASHBOARD=1
deploy:
resources:
limits:
memory: 4G
cpus: "2.0"state.db. On those hosts, use a named volume instead: -v hermes-data:/opt/data. On a Linux server, the bind mount is fine.
Upgrading
docker pull nousresearch/hermes-agent:latest
docker rm -f hermes
# re-run the "docker run -d ..." command from step 3 (or: docker compose up -d)If you use browser-automation tools, add --shm-size=1g to the run command, because Playwright needs shared memory.
A Mac mini or an always-on MacBook makes a good home for Hermes. On a Mac it can also reach the iMessage bridge and local files. Homebrew installs the tooling, uv manages the Python environment, and launchd restarts the gateway after reboots and crashes.
-
Install Homebrew (skip if you already have it)
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)" -
Install the dependencies
The Hermes installer can fetch these itself, but installing them through Homebrew keeps them updated with
brew upgrade.brew install uv git ripgrep ffmpeg node -
Install Hermes Agent
The official script uses
uvto create an isolated Python 3.11 environment and puts thehermescommand on your PATH.curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash source ~/.zshrc hermes --version -
Run the setup wizard
hermes setup # provider, model, tools hermes doctor # verify dependencies and config -
Keep the gateway alive with launchd
hermes gateway startruns the gateway in the background for the current session. To have it start at login and restart if it crashes, create a LaunchAgent. First find the full path to the binary:which hermes # e.g. /Users/you/.local/bin/hermesSave the following as
~/Library/LaunchAgents/com.hermes.gateway.plist, replacing both/Users/youpaths:<?xml version="1.0" encoding="UTF-8"?> <!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd"> <plist version="1.0"> <dict> <key>Label</key><string>com.hermes.gateway</string> <key>ProgramArguments</key> <array> <string>/Users/you/.local/bin/hermes</string> <string>gateway</string> <string>run</string> </array> <key>EnvironmentVariables</key> <dict> <key>PATH</key><string>/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin:/Users/you/.local/bin</string> </dict> <key>RunAtLoad</key><true/> <key>KeepAlive</key><true/> <key>StandardOutPath</key><string>/tmp/hermes-gateway.log</string> <key>StandardErrorPath</key><string>/tmp/hermes-gateway.err</string> </dict> </plist>launchctl load ~/Library/LaunchAgents/com.hermes.gateway.plist launchctl list | grep hermes # should show a PID tail -f /tmp/hermes-gateway.log -
Stop the Mac from sleeping
A sleeping Mac means a sleeping agent. In System Settings โ Energy, enable "Prevent automatic sleeping when the display is off", or run
sudo pmset -a sleep 0on a desktop Mac.
launchctl unload ~/Library/LaunchAgents/com.hermes.gateway.plist. To update Hermes, run hermes update and then unload and load the plist again.Hermes runs natively on Windows through a PowerShell installer. WinGet, which ships with Windows 10 and 11, installs the supporting tools in one go.
-
Install the dependencies with WinGet
Open Windows Terminal (PowerShell) and run:
winget install --id Git.Git -e winget install --id astral-sh.uv -e winget install --id OpenJS.NodeJS.LTS -e winget install --id BurntSushi.ripgrep.MSVC -e winget install --id Gyan.FFmpeg -eClose and reopen the terminal so the new PATH entries load.
-
Allow local scripts (one time)
Set-ExecutionPolicy -Scope CurrentUser RemoteSigned -
Install Hermes Agent
iex (irm https://hermes-agent.nousresearch.com/install.ps1) hermes --version -
Run the setup wizard
hermes setup hermes doctor -
Run the gateway in the background
For a quick test, run
hermes gateway start. To have the gateway start whenever you log in, register a scheduled task:$hermes = (Get-Command hermes).Source $action = New-ScheduledTaskAction -Execute $hermes -Argument "gateway run" $trigger = New-ScheduledTaskTrigger -AtLogOn $settings = New-ScheduledTaskSettingsSet -RestartCount 999 -RestartInterval (New-TimeSpan -Minutes 1) -ExecutionTimeLimit 0 Register-ScheduledTask -TaskName "HermesGateway" -Action $action -Trigger $trigger -Settings $settings Start-ScheduledTask -TaskName "HermesGateway" hermes gateway status -
Disable sleep on the host
In Settings โ System โ Power, set "When plugged in, put my device to sleep after" to Never.
Verify your install
| Command | What it tells you |
|---|---|
hermes doctor | Checks dependencies, config and keys. hermes doctor --fix repairs common problems. |
hermes chat -q "hello" | Sends a single test prompt and confirms the provider and model respond. |
hermes gateway status | Shows whether the gateway is running and which platforms are connected. |
hermes update | Upgrades a native (non-Docker) install to the latest release. |
- Direct API (cheapest per token): add
DEEPSEEK_API_KEYto~/.hermes/.envand choose DeepSeek inhermes model. - OpenCode (flat subscription): set
OPENCODE_GO_API_KEYorOPENCODE_ZEN_API_KEYand pick theopencode-gooropencode-zenprovider. - Command Code: set
COMMANDCODE_API_KEY(providercommandcode) to reuse your plan in Hermes, and use thecmdCLI for coding work. - Pick
deepseek-flashfor everyday turns anddeepseek-v4-profor harder reasoning.
echo 'DEEPSEEK_API_KEY=sk-your-key' >> ~/.hermes/.env
hermes model # choose DeepSeek โ deepseek-flashWhich DeepSeek model?
DeepSeek currently serves two API models. Both have a 1M-token context window, tool calling and JSON output, and both run in thinking mode by default.
| Model id | Cached input | Uncached input | Output | Use it for |
|---|---|---|---|---|
deepseek-flashV4.1 Flash | $0.003 โ $0.006 | $0.15 โ $0.30 | $0.60 โ $1.20 | Default agent model: chat, cron jobs, tool use, summaries. Supports vision. |
deepseek-v4-proV4 Pro | $0.022 โ $0.044 | $0.66 โ $1.32 | $1.98 โ $3.96 | Harder reasoning, multi-step coding and planning. |
Prices are per 1M tokens, shown as off-peak โ peak. Peak hours are 01:00โ04:00 and 06:00โ10:00 UTC, MondayโFriday. The legacy name deepseek-v4-flash is still accepted and billed as Flash. Source: DeepSeek pricing, November 2026.
Compare the three routes
Direct DeepSeek API
Pay-as-you-go with automatic prompt caching and the full 1M context. Best for always-on agents.
OpenCode gateway
One subscription (Go, from $10/mo) or Zen key covers DeepSeek plus Kimi, GLM, Qwen and more, so you can switch models freely.
Command Code
A terminal coding agent built for open models. Your plan doubles as a Hermes provider.
| Direct API | OpenCode | Command Code | |
|---|---|---|---|
| Hermes provider id | deepseek | opencode-go / opencode-zen | commandcode |
| Key variable | DEEPSEEK_API_KEY | OPENCODE_GO_API_KEY / OPENCODE_ZEN_API_KEY | COMMANDCODE_API_KEY |
| Billing | Per token, prepaid balance | Subscription with usage allowances (Go) or credits (Zen) | Command Code plan (GOAT, Pro, Max or Provider) |
| Other models | DeepSeek only | Many open models | Many open models, plus Claude via commandcode-anthropic |
Option A: Direct DeepSeek API
Recommended for most people.
-
Create an API key
Sign in at platform.deepseek.com, add a small top-up (a few dollars lasts a long time), and create a key under API Keys.
-
Add the key to Hermes
~/.hermes/.env
DEEPSEEK_API_KEY=sk-xxxxxxxxxxxxxxxxxxxxxxxxOn Docker, this is the
.envfile inside your mounted data folder. You can also pass-e DEEPSEEK_API_KEY=...todocker run. -
Select the provider and model
The interactive way:
hermes model # โ choose DeepSeek โ choose deepseek-flashOr set it directly in config:
~/.hermes/config.yamlmodel: provider: deepseek default: deepseek-flash -
Test it
hermes chat -q "Reply with the word OK" hermes chat --provider deepseek --model deepseek-v4-pro -q "Plan a 3-step refactor"Restart the gateway (
hermes gateway restartordocker restart hermes) so chat platforms pick up the new model.
Alternative: generic OpenAI-compatible endpoint
If your Hermes version lacks the built-in DeepSeek option, or you want to pin the endpoint yourself, configure DeepSeek as a custom provider:
model:
provider: custom
base_url: https://api.deepseek.com/v1
key_env: DEEPSEEK_API_KEY
default: deepseek-flashOption B: OpenCode gateway
Predictable monthly billing and many models behind one key.
OpenCode runs two hosted gateways that Hermes supports natively. OpenCode Go is a low-cost subscription (from $10/month) with generous allowances for DeepSeek V4.1 Flash, DeepSeek V4 Pro, Kimi, GLM, Qwen, MiniMax and others. OpenCode Zen is a pay-as-you-go key for a curated list of models.
-
Subscribe and copy your key
Sign up for OpenCode Go (this referral link adds $5 in credit) and copy the API key from the console.
On Go, DeepSeek models require the Global region. In the OpenCode console, open Settings โ Privacy โ Regions and enable it (the default is Europe & United States only). -
Add the key to Hermes
~/.hermes/.env
# OpenCode Go subscription OPENCODE_GO_API_KEY=your-go-key # or OpenCode Zen (pay-as-you-go) # OPENCODE_ZEN_API_KEY=your-zen-key -
Pick a DeepSeek model through the gateway
hermes model # โ choose "OpenCode Go" (or "OpenCode Zen") โ pick a DeepSeek model from the listTo see the exact model ids your plan offers, run
curl https://opencode.ai/inference/go/v1/models. The resulting config looks like this:~/.hermes/config.yamlmodel: provider: opencode-go default: <deepseek-model-id-from-the-list>
Option C: Command Code
For people who also want a terminal coding agent on open models.
Command Code is a terminal coding agent (cmd) built for open models such as DeepSeek V4.1 Flash and V4 Pro. You can use it in two ways alongside Hermes.
C1. Use your Command Code plan as Hermes' provider
COMMANDCODE_API_KEY=your-commandcode-keyhermes model
# โ choose "Command Code" โ pick DeepSeek V4.1 Flash or V4 Procommandcode-anthropic provider.C2. Run the Command Code CLI on DeepSeek (BYOK)
Hermes is your always-on assistant. For hands-on coding sessions, run cmd in a project with your own DeepSeek key:
npm i -g command-code
cmd login
cd your-project && cmd
# inside cmd: /connect โ "(BYOK) Add your own provider" โ type "deepseek"
# the endpoint and model list are prefilled; paste your DeepSeek keyIf you prefer config files, define the provider in ~/.commandcode/providers.json:
{
"provider": {
"deepseek-direct": {
"name": "DeepSeek (direct)",
"baseURL": "https://api.deepseek.com/v1",
"apiKey": "$DEEPSEEK_API_KEY",
"models": {
"deepseek-flash": { "contextWindow": 1000000 },
"deepseek-v4-pro": { "contextWindow": 1000000 }
}
}
}
}Command Code also runs as an ACP server (cmd acp), so editors such as Zed can drive it directly.
Cost & reliability tips
- Keep the prompt prefix stable. DeepSeek's cache matches on the start of the prompt. Avoid putting timestamps or random content at the top of
SOUL.mdor your system prompt, so cache hits stay high. - Default to Flash, escalate to Pro. Use
deepseek-flashday to day and switch with/modelmid-session when a task needs deeper reasoning. - Schedule heavy cron jobs off-peak. Batch research or summarisation jobs that run outside 01:00โ04:00 and 06:00โ10:00 UTC on weekdays cost half as much.
- Add a fallback. Hermes supports credential pooling and automatic failover. Pairing the direct API with OpenCode Go keeps your agent answering if one provider rate-limits you.
- Watch your balance. Set a low-balance alert on the DeepSeek platform. A runaway loop is the only realistic way to rack up a large bill.
- Message @BotFather, send
/newbot, and copy the bot token. - Message @userinfobot to get your numeric Telegram user ID.
- Put
TELEGRAM_BOT_TOKENandTELEGRAM_ALLOWED_USERSin~/.hermes/.env, or runhermes gateway setup. - Restart the gateway and send your bot a message from your phone. Voice notes are transcribed automatically.
TELEGRAM_BOT_TOKEN=123456789:AA...your-token
TELEGRAM_ALLOWED_USERS=987654321Telegram is the best-supported chat platform in Hermes, with commands, inline approval buttons, voice transcription, file transfer and topic threads. It connects outbound from your machine, so you don't need to open ports or set up a domain, even behind home NAT.
1. Create a bot with @BotFather
- Open @BotFather
In Telegram, search for @BotFather (it has the blue verified tick) and tap Start.
- Send
/newbotChoose a display name (for example "My Hermes"), then a username ending in
bot(for examplemy_hermes_agent_bot). - Copy the token
BotFather replies with a token like
123456789:AAH.... Treat it like a password, because anyone with it can control your bot. - Optional polish
Use
/setuserpicfor an avatar,/setdescriptionfor the intro text, and/setprivacyfor group behaviour (see Groups).
/revoke to @BotFather to issue a new one, then update your .env.2. Get your numeric ID from @userinfobot
Bot usernames are public, so anyone who finds yours can message it. Hermes blocks this with a whitelist of numeric Telegram user IDs, and the gateway denies everyone by default until you add yourself.
- Message @userinfobot
Search for @userinfobot and tap Start. It replies with your Id, a number like
987654321. (@get_id_bot works too.) - Collect IDs for anyone else you trust
Have family members or teammates do the same and send you their numbers. Usernames won't work here; only the numeric ID will.
3. Configure the Hermes gateway
Option A: the wizard
hermes gateway setup
# โ select Telegram โ paste the bot token โ enter your user IDOn Docker: docker run -it --rm -v ~/.hermes:/opt/data nousresearch/hermes-agent gateway setup, then docker restart hermes.
Option B: edit .env by hand
Both values belong in ~/.hermes/.env, not in config.yaml:
TELEGRAM_BOT_TOKEN=123456789:AAH-your-token-here
TELEGRAM_ALLOWED_USERS=987654321
# Several people: comma-separated numeric IDs
# TELEGRAM_ALLOWED_USERS=987654321,123123123
# Optional: where cron jobs and automated messages are delivered
# TELEGRAM_HOME_CHANNEL=987654321Start or restart the gateway
| Install type | Command |
|---|---|
| Docker | docker restart hermes |
| macOS (launchd) | launchctl unload ~/Library/LaunchAgents/com.hermes.gateway.plist && launchctl load ~/Library/LaunchAgents/com.hermes.gateway.plist |
| Windows (Task Scheduler) | Stop-ScheduledTask HermesGateway; Start-ScheduledTask HermesGateway |
| Manual | hermes gateway restart |
hermes gateway status # Telegram should show as connectedOpen your bot in Telegram, tap Start, and say hello. If it replies, you're done.
TELEGRAM_ALLOWED_USERS set at all times. Leave Hermes' command approval on, so risky actions such as rm -rf or git reset --hard ask you through an inline button before running. Never commit .env to git.4. Mobile workflows on iOS & Android
There's nothing extra to install. The official Telegram app is your Hermes client, and the same chat syncs across your phone, tablet and desktop.
Telegram for iOS
Pin the bot chat to the top of your chat list. Long-press the app icon for a quick "New Message" shortcut. Share sheet โ Telegram sends photos, PDFs and links straight to your agent. Add the chat to a Focus filter so agent notifications still reach you.
Telegram for Android
Long-press the bot chat โ Add to Home Screen for a one-tap shortcut. Share from any app to forward files. Set a custom notification channel for the bot so its alerts are easy to tell apart.
Desktop & Web
Telegram Desktop and web.telegram.org share the same history, so you can start a task on your phone and pick up the result at your desk.
Things to try from your phone
| Workflow | How |
|---|---|
| ๐๏ธ Voice notes | Hold the mic button and talk. Hermes transcribes it (local faster-whisper by default, or Groq/OpenAI with a key) and replies in text, or with voice if TTS is set up. |
| ๐ Files & photos | Send a screenshot, PDF or log file and ask about it. DeepSeek Flash supports vision. |
| โฐ Reminders & cron | "Every weekday at 8am, send me a summary of my unread GitHub notifications." Results arrive in your home channel. |
| โ Approvals on the go | When the agent wants to run something risky on your server, tap the inline Approve or Deny button. |
| ๐ Switch models | Send /model to move between deepseek-flash and deepseek-v4-pro mid-conversation. |
| ๐งต Separate topics | In a group with Topics enabled, each topic gets its own session. Use one for work, one for home and one for research. |
For voice replies with Edge TTS (the default), the host needs ffmpeg installed (brew install ffmpeg or sudo apt install ffmpeg) so replies arrive as proper voice bubbles. The Docker image already includes it.
Groups & scheduled messages
- Privacy mode is on by default. In groups, the bot only sees
/commands, replies to its own messages, and mentions. To let it read everything, send @BotFather/mybotsโ Bot Settings โ Group Privacy โ Turn off, then remove and re-add the bot to the group. Making the bot a group admin also works. - Restrict which groups it serves with
TELEGRAM_GROUP_ALLOWED_CHATS(comma-separated chat IDs). - Observe but stay quiet: set
require_mention: trueandobserve_unmentioned_group_messages: trueundertelegram:inconfig.yaml. The agent then remembers the conversation but only answers when you @-mention it. - Home channel:
TELEGRAM_HOME_CHANNELsets where cron output and proactive messages go. Use your own user ID for a private feed.
Troubleshooting
| Symptom | Fix |
|---|---|
| Bot never replies | Check the token for missing characters or trailing spaces, restart the gateway, and run hermes gateway status. |
| Bot replies "not authorised" or ignores you | Your numeric ID isn't in TELEGRAM_ALLOWED_USERS, or you used a username instead of the number. Restart after editing. |
| Works in DMs, silent in groups | Privacy mode is on. Mention the bot, or turn privacy off and re-add the bot. |
| Telegram blocked on your network | Set TELEGRAM_PROXY (or telegram.proxy_url, e.g. socks5://127.0.0.1:1080). |
| Anything else | Run hermes doctor --fix and check the gateway logs (docker logs -f hermes or /tmp/hermes-gateway.log). |