How to Set Up Hermes Agent on a VPS with Telegram in Under 30 Minutes: Complete Setup Guide
Hermes Agent runs on your own VPS, connects via Telegram, and uses your ChatGPT subscription — no API key billing. Here's the complete setup walkthrough.
You Can Have Hermes Running on Telegram in Under 30 Minutes
Most people assume self-hosted AI agents require a home server, a Mac Mini, or at minimum a weekend of configuration. That assumption is wrong. With Hostinger’s one-click Docker install for Hermes, a Telegram bot from BotFather, and OpenAI Codex OAuth for authentication, you can have a fully functional personal AI agent running on a VPS and responding to your Telegram messages in under 30 minutes — without touching a single API billing dashboard.
This guide walks through the exact steps. No assumed Linux expertise. No hand-waving over the hard parts.
What You’re Actually Building
Hermes Agent is an open-source project from Noose Research — 140,000 GitHub stars, MIT licensed, and growing fast. It runs on your own infrastructure, connects to messaging platforms like Telegram, and improves itself over time by writing and updating its own skills.
The setup you’re building here has three components:
- A VPS on Hostinger — your always-on server in the cloud
- A Telegram bot — your interface for talking to the agent from your phone
- OpenAI Codex OAuth — authentication that uses your existing ChatGPT subscription ($20–$200/month) instead of separate API key billing
That third point is worth pausing on. You don’t need a new API account. You don’t need to set up billing. If you already pay for ChatGPT, Hermes can use that subscription directly via OAuth. That’s a meaningful difference from most self-hosted agent setups.
Coding agents automate the 5%. Remy runs the 95%.
The bottleneck was never typing the code. It was knowing what to build.
Step 1: Spin Up Your VPS on Hostinger
Go to Hostinger and navigate to their VPS plans. The KVM 2 plan is a reasonable starting point — it gives you enough CPU and RAM to run Hermes comfortably, and you can scale up later if you add more agents or heavier workloads.
When choosing your billing period, pick at least 12 months. The annual plan unlocks the promo code Nate Herk for an additional 10% off. You’re going to want this server running continuously anyway, so the annual commitment makes sense.
Choose your OS: Ubuntu 24.04 LTS. This is the most stable choice for running Docker containers.
Server location: Pick whatever’s geographically closest to you. It affects latency when your agent is responding to Telegram messages.
After payment, Hostinger will provision your VPS. This takes a couple of minutes. While it’s spinning up, set a root password — you’ll need it to SSH in. If you forget it later, you can regenerate it from the dashboard.
Now you have a live server with an IP address. That’s your foundation.
Step 2: Install Hermes via One-Click Docker
Here’s where Hostinger’s setup saves you real time. From your VPS dashboard, navigate to the Docker manager. Click Compose, then One-click deploy. Search for Hermes and select it.
You’ll be prompted to set an admin username and admin password. Copy these somewhere safe — a local notes file, a password manager, or if you’re managing multiple agents, a dedicated Claude Code project folder works well. The point is: don’t lose these credentials.
Click Deploy. The container will spin up in under a minute.
Once it’s running, you’ll see a button to open the Hermes interface. Click it. This takes you into the Docker container’s terminal — not the root VPS terminal. That distinction matters later when you’re managing API keys.
A quick note on why Docker matters here: each Hermes agent runs in its own isolated container with its own .env file, its own memory, and its own credentials. If you eventually run a marketing agent and a finance agent on the same VPS, they won’t share keys or bleed context into each other. The VPS is the office building; each container is a separate office.
Step 3: Run the Onboarding and Choose OpenAI Codex OAuth
When the Hermes interface opens, you’ll be walked through a quick setup sequence. Hit enter to start.
The first real decision is your inference provider. You’ll see a long list of options. Choose OpenAI Codex.
This triggers an OAuth flow. Hermes gives you a URL — open it in your browser, sign into your ChatGPT account, grant access, and copy the nine-digit code it returns. Paste that code back into the terminal and hit enter.
You’ll see: Login successful.
Now choose your model. GPT-4.5 or GPT-5.5 are both reasonable choices depending on what your subscription tier supports.
Now you have an authenticated agent. No API keys, no usage billing dashboard to monitor.
Everyone else built a construction worker.
We built the contractor.
One file at a time.
UI, API, database, deploy.
Step 4: Create Your Telegram Bot via BotFather
Open Telegram and search for @BotFather. Start a conversation and send:
/newbotBotFather will ask for a name (this is the display name, like “My Hermes Assistant”) and then a username (must end in bot, must be unique across all of Telegram). The username is harder to get right on the first try — common names are taken. Try something specific to you.
Once you’ve got a valid username, BotFather returns a bot token. It looks like a long string of numbers and letters. Copy it.
Go back to your Hermes terminal. When it asks for your Telegram bot token, paste it in and hit enter. The token may not visually appear in the terminal as you paste — that’s normal behavior for password-style inputs. Hit enter anyway.
Next, Hermes asks for an allowed user ID. This is how it restricts access to your bot — only the Telegram accounts you whitelist can talk to it.
To get your user ID, open Telegram and search for @userinfobot. Send it any message. It replies immediately with your numeric user ID. Copy that number, paste it into the Hermes terminal, and confirm it as your home channel.
Now you have a Telegram bot connected to your Hermes agent.
Step 5: Verify the Connection (and Fix It If It’s Broken)
Go to Telegram, find the bot you just created, hit Start, and send “hello.”
There’s a reasonable chance nothing happens the first time. This is normal — the Hermes gateway sometimes needs a nudge after initial setup.
Go back to your Hermes terminal and tell it: “The Telegram connection doesn’t seem to be working. I just sent hello and got no response.” Hermes will investigate, run some terminal commands, and restart the gateway. Once it reports back that the gateway is online, try sending “hello” again from Telegram.
When it works, you’ll see the typing indicator appear in the top left of the Telegram chat, and Hermes will respond.
You now have a working end-to-end setup: VPS → Docker container → Hermes agent → Telegram.
Step 6: Add API Keys Safely
At some point you’ll want to connect Hermes to external services — GitHub, Perplexity, Open Router, whatever fits your workflow. The temptation is to just paste the key into the chat. Don’t.
The correct method is to use the terminal directly. In your Hermes Docker container terminal, run:
hermes config set GITHUB_TOKEN [your-token-here]This writes the key to /opt/data/.env inside the container — not into the conversation history, not into any log that gets synced to GitHub. The agent can read it from there when it needs it, but it never appears in your chat.
This matters more than it might seem. If you’re using a cloud-hosted model (which you are, via Codex OAuth), your conversation history passes through external servers. Keeping secrets out of that stream is basic hygiene.
How Remy works. You talk. Remy ships.
When you need to edit or delete a key, you’ll need to access the .env file inside the Docker container specifically — not the root VPS .env. Ask Hermes for the exact nano command to open the container’s env file. It knows the path.
Step 7: Connect to GitHub and Set Up Your First Cron
The first thing worth doing after onboarding is connecting Hermes to a private GitHub repo. If your VPS ever goes down or the container gets corrupted, your skills, memory files, and configuration are gone — unless they’re backed up.
Tell Hermes: “I want to set up a private GitHub repo as a backup for this agent. Can you help me figure out how to do that? I’ll give you whatever API key you need.”
Hermes will walk you through creating a GitHub personal access token. When you have it, use hermes config set GITHUB_TOKEN [token] as described above.
Then tell it: “Every night at 12am Central time, push changes to this GitHub repo.”
That’s it. One sentence. Hermes will create a skill called something like nightly-github-sync and register a cron job. It handles the UTC conversion, daylight saving edge cases, and the git commands. You don’t write any of that.
This is one of the things that distinguishes Hermes from tools like Claude Code for on-the-go use. You can set up scheduled automations with Claude Code, but it typically requires you to leave infrastructure running or work within daily routine limits. Hermes crons run independently on your VPS, fire at the scheduled time, and report back to your Telegram chat. For a deeper look at how the cron system fits into Hermes’s broader architecture, the five-pillar breakdown of how Hermes learns and schedules is worth reading.
Step 8: Onboard the Agent Itself
Once the infrastructure is stable, spend 5–10 minutes just talking to Hermes. Tell it your name, what you’re working on, what your goals are, what you don’t like. It will start building your user.md and memory.md files automatically — these get loaded at the start of every session so the agent doesn’t wake up blank.
You’ll notice it doing things like “adding user memory” and “updating memory.md” as you talk. That’s the self-improving loop in action. The more you correct it, the better those files get.
One useful framing: think of this like onboarding an actual employee. You wouldn’t hand a new hire your credit card and full admin access on day one. Give Hermes scoped API keys. Give it its own email address if it needs one. Give each agent only the credentials it needs for its specific job.
If you’re thinking about building multiple agents — a marketing one, a finance one — the OpenClaw best practices guide has useful thinking on how to structure agent separation, even though it’s focused on a different tool. The mental models transfer.
Managing Multiple Agents as You Scale
Once you have one Hermes running well, you’ll probably want more. The Docker approach makes this straightforward: each new agent gets its own container on the same VPS, its own .env, its own memory, its own Telegram bot.
Not a coding agent. A product manager.
Remy doesn't type the next file. Remy runs the project — manages the agents, coordinates the layers, ships the app.
The practical problem is keeping track of which agent is on which server with which credentials. A simple solution: create a dedicated Claude Code project folder called something like vps-agents. Inside it, keep a subfolder for each agent with an .env file containing the admin username, admin password, VPS IP, and container name. When something breaks — and occasionally something will — you have everything you need to diagnose it without hunting through dashboards.
This is also where platforms like MindStudio offer a different path: if you want to build agents and workflows without managing VPS infrastructure at all, MindStudio’s visual builder handles orchestration across 200+ models and 1,000+ integrations without you touching a terminal. It’s a different tradeoff — less control over the underlying infrastructure, but also less to maintain.
For the Hermes setup specifically, the Claude Code project approach gives you a local source of truth that survives any individual agent going down.
What Hermes Can Do Once It’s Running
After setup, the 91 built-in skills cover a surprising range: browser automation, image generation, text-to-speech, vision, terminal commands, task planning. You don’t install any of these manually — they’re available immediately.
Beyond that, there are 520+ community skills at the Hermes skills hub, plus 16 official Anthropic skills. You can install any of them by dropping the URL into your Telegram chat and saying “install this skill.”
The cron system is where things get interesting for ongoing workflows. You can say “for the next 12 hours, check for new YouTube comments every 10 minutes and respond to them” — and it will. You can say “every morning at 6am, send me a summary of overnight news in my industry” — and it will. Each cron fires an isolated session, runs the task, and reports back to your Telegram.
If you’re curious about how this compares to building agent workflows with code, Claude Code’s agentic workflow patterns covers the spectrum from one-shot prompts to full autonomous loops — useful context for understanding where Hermes fits in a broader agent stack.
One more thing worth knowing: the skills system is just markdown files with YAML front matter. If you ever want to migrate your skills to a different agent framework, or share them with a teammate, you’re working with plain text files in a GitHub repo. There’s no proprietary format locking you in. Tools like Remy take a similar philosophy in a different domain — your spec is annotated markdown, the compiled output (TypeScript backend, database, auth, deployment) is derived from it, and you own everything.
After the First Week
The setup is the easy part. The value compounds as you use it.
When Hermes gets something wrong, correct it on the spot and tell it to update the relevant skill or memory file. When you find yourself giving the same instruction twice, ask it to write a skill for it. When the tone feels off, have it edit its soul.md. When something behaves strangely, ask it to read its own memory.md out loud — stale memory is the most common cause of weird agent behavior.
The agent you have in a month will be meaningfully different from the one you set up today. That’s the point.
