Deploy a self-improving AI assistant on a VPS, connect it to your phone via Telegram, and put scheduled jobs and custom skills to work in under an hour. No prior server experience needed.
hermes setup. The wizard handles the AI provider, model, and Telegram bot in one pass.Hermes is a self-improving AI assistant that runs 24/7 on a server you control. Unlike a chat tab in your browser, it stays online, messages you on Telegram (or Discord, Slack, WhatsApp, Signal — 15+ platforms via a single gateway), and can act on a schedule. Four things make it different:
Hermes needs a machine that stays online 24/7. Running it on your laptop works for testing, but the moment your computer sleeps, scheduled jobs and the always-on gateway stop. A VPS solves that and gives you a clean, isolated environment that you can wipe and redeploy if anything breaks.
Pick a plan with the specs above. If you're new to VPSes, the one-click Hermes template route is the lowest-friction option — no manual Docker setup required.
During provisioning you'll be asked to set credentials for the Hermes web terminal. Use a long, randomly generated password and store both in a password manager. You'll need them for any future maintenance.
Once deployment finishes, the Docker project will be named something like hermes-agent-abcd. Copy the last four characters — you'll need them to navigate to the right directory.
Most hosts ship a browser-based SSH terminal. If you're SSH'ing in directly, that works too. Either way, you'll be at a Linux shell prompt for the next steps.
cd /docker/hermes-agent-XXXXReplace XXXX with the suffix you copied earlier.
docker compose exec -it hermes-agent /bin/bashYou're now inside the Hermes container. All hermes CLI commands run from here.
hermes setupChoose Quick Setup when prompted. This walks you through provider, API key, model, and messaging in one flow.
You'll see Anthropic, OpenAI, OpenRouter, and others. OpenRouter is the most flexible — a single API key gives you access to 200+ models from every major provider, and you can switch between them later with a single command.
Go to openrouter.ai, sign up, and verify your email.
Open the API Keys section and click Create Key. Name it "Hermes Agent." Set a credit limit (e.g., $50) — this is your safety net. If usage ever spikes, the key stops working before you spend more than that. Set a reset cadence if you want monthly recurring caps.
Open the Credits section and add credits or set up auto-top-up. Without credits, your key won't load any models.
Back in the terminal, paste the key (use Ctrl + Shift + V in most web terminals). Nothing will appear on screen — that's intentional. Press Enter.
The default is often a top-tier model like Claude Opus, which is expensive for everyday chatting. Switch to something balanced like a Sonnet-class model or a GPT mini for daily work — you can always upgrade specific jobs later (see Switching Models).
Telegram is the quickest first channel: no developer portal, no OAuth dance, just two short bot conversations.
When the wizard asks which platforms to configure, select Telegram.
Open Telegram (desktop or mobile), search for @BotFather (the verified one, with the blue check). Tap Start, then send /newbot. Give it a display name (e.g., "Hermes Agent") and a unique username ending in bot (e.g., YourNameHermesBot). BotFather will return a bot token. Copy it.
Back in the wizard, paste the token (again, nothing will appear) and press Enter.
In Telegram, search for @UserInfoBot and tap Start. It returns your numeric user ID. Copy it.
Paste the user ID into the wizard prompt for "Allowed user IDs." Only the IDs you list here can talk to your bot — anyone else who finds it is silently ignored.
The wizard will offer to use your user ID as the "home channel" — that's where Hermes delivers cron job results, cross-platform messages, and proactive notifications. Press Y to accept.
hermes setup tools.The gateway is the always-on process that keeps your bot connected to Telegram (and any other platforms you've configured). Without it, your messages won't reach the agent.
hermes gateway installhermes gateway runYou'll see a "gateway starting" message. From this point on, you can close the web terminal — you'll do almost everything else from Telegram.
Open the chat with your bot in Telegram and tap Start. You may see a brief "unknown command" reply because Hermes doesn't ship with a custom /start handler — that's normal. Then send a real first message:
Hey, you're running on a VPS inside a Docker container.
Check your environment and tell me what tools and skills you currently have available.This single message gives the agent context about its own environment and gives you a clean inventory of what you're working with. A typical fresh install reports about 28 tools and 75 pre-installed skills.
A skill is a reusable recipe Hermes uses to handle a specific kind of task. It comes with a starter library covering web research, file work, code, scheduling, and more — and it can write new skills for you on demand.
Send: "Tell me each of the skills you currently have installed." You'll get a categorised list. Most common asks are already covered.
Tell it what you're trying to do — e.g., "I want help with weekly content research and planning. What new skills can I install for this?" If it has everything, it'll say so. If not, it'll suggest which skills to add and walk you through the install.
Run a real task, then ask Hermes to save the approach as a skill. Example:
Research the top trending AI tools right now and come back
with the top three that would make for an interesting tutorial video.
When you're finished, create a new skill based on your approach
and call it youtube-video-research.Now any future request like "use the youtube-video-research skill" reuses that exact workflow without rebuilding it from scratch.
Hermes ships with a built-in memory store. It remembers your name, preferences, ongoing projects, and corrections — without you having to repeat yourself every conversation.
Send: "Show me what you remember about me so far." You'll get a structured rundown of stored facts and preferences.
Just tell it. Example: "Remember that I prefer responses to be short and direct, no long explanations unless they're needed." Confirm by asking it to show its memory again.
The built-in store handles facts. Honcho is a paid add-on that builds a richer model of how you work over time — it picks up on patterns and adjusts based on what you correct it on. To explore it, run inside the container:
hermes memory setupSelect Honcho and follow the prompts. The default built-in memory is enough to start with.
This is where Hermes feels less like a chatbot and more like an assistant. Tell it what to do and when, in plain English.
Set up a weekly job that runs every Monday at 9 a.m.
that researches the top three trending AI tools using the
youtube-video-research skill we created earlier.It confirms the schedule, the skill, and the delivery channel (your home channel by default). Manage jobs with:
You don't have to pick one model and live with it. From any chat, send:
/modelYou'll get a picker showing your current model and provider, with a paginated list of alternatives. Heavy thinking task? Switch to Opus or GPT-5 class. Quick chat? Drop to a Haiku or mini-class model and keep costs down.
You can also assign a different model to a specific scheduled job. Example:
Change the weekly AI tools research job to run on Claude Opus.
Keep my default chat model as is.Now that one job uses the heavyweight model while everyday chats stay on the cheaper default.
Hermes is free. The VPS is cheap. The AI usage is where bills appear if you're not careful.
You're on the host shell, not inside the container. Run:
cd /docker/hermes-agent-XXXX
docker compose exec -it hermes-agent /bin/bashThen retry your hermes command.
Most common causes, in order: (1) the gateway isn't running — re-run hermes gateway run; (2) your Telegram user ID isn't in the allowed list — re-run hermes setup and add it; (3) the bot token is wrong — re-create one via BotFather and paste it again.
Your OpenRouter key has hit its credit limit or your account is out of funds. Open the OpenRouter Credits page and either add credits or raise the per-key cap. Then retry — no need to restart Hermes.
First, ask the agent: "Show me a list of all current jobs and the next run time." If the job is paused, resume it. If the gateway crashed, restart with hermes gateway run. If the cron is correct but no message arrived, check that the home channel is still your Telegram ID with hermes setup.
That's intentional. Web terminals hide pasted secrets. Press Enter after pasting — if the key was wrong, the wizard will tell you on the next step.
Run hermes gateway setup inside the container. You'll see options for Discord, Slack, WhatsApp, Signal, and others. The agent uses the same memory and skills regardless of which channel you message it from.
Tell Hermes how you like to work: response length, tone, your name, timezone, your role. The earlier you set this, the better every future conversation gets.
Don't try to automate everything in week one. Pick one daily friction — morning briefing, weekly competitor digest, end-of-day summary — and build the skill + scheduled job for it.
Run hermes setup tools for any of the X-marked tools you'll use (search APIs, GitHub, calendar, etc.). Skip the rest until you have a concrete reason.
Before any major change to the VPS, take a snapshot from your host's dashboard. If something breaks, you can restore in minutes instead of redeploying from scratch.
Was this guide helpful?