How to Deploy Hermes Agent on a VPS in Under an Hour: Step-by-Step Docker Setup Guide

A Persistent AI Agent on Your Own Server, Running in Under an Hour

Most people who want a personal AI agent end up with one of two outcomes: a chatbot that forgets everything between sessions, or a local setup that only works when their laptop is open. Neither is what they actually wanted. What you actually want is something running on infrastructure you control, available from your phone at 2am, executing scheduled tasks while you sleep. You can have that in under an hour using Hermes Agent, a Hostinger VPS KVM 2 plan, and the one-click Docker install that Hostinger ships for exactly this purpose.

Hermes Agent is an open-source MIT-licensed project from Noose Research with 140,000 GitHub stars — one of the fastest-growing open-source projects on GitHub as of mid-2026. It runs in a Docker container on your VPS, connects to Telegram as its primary interface, and uses OpenAI Codex as its inference backend — meaning your existing $20/month ChatGPT subscription can power it instead of API keys. That last part is not a minor detail. It makes this potentially the cheapest way to run a frontier-model agent on persistent infrastructure.

This guide walks through the exact setup: VPS provisioning, Docker deployment, Telegram bot creation, GitHub sync, and your first scheduled cron job.

---

What You’re Actually Building Here

Before the steps, a concrete picture of the end state.

You’ll have a Hermes Agent instance running inside a Docker container on a cloud VPS. It connects to a Telegram bot you own. You message it from your phone — text or voice — and it responds with full tool access: browser automation, terminal commands, image generation, text-to-speech, and a skill library with 85 tools pre-installed out of the box.

It also runs scheduled automations (crons) without you being present. The example we’ll build: a nightly GitHub sync that commits your agent’s memory, skills, and configuration to a private repo every night at midnight your local time. If your VPS ever dies, you restore from that repo and lose nothing.

The agent’s memory persists across sessions via two files: user.md (your preferences, style, things you don’t want repeated) and memory.md (projects, business context, environment). These load at session start so the agent isn’t starting cold every time. Think of it like the movie Memento — the agent wakes up stateless, and these files are the notes tattooed on its arms.

If you’re evaluating whether Hermes fits your workflow versus other options, there’s a detailed comparison of Hermes Agent vs. Claude Code vs. OpenClaw worth reading separately. This post is purely about getting it deployed.

---

What You Need Before You Start

Accounts:

• Hostinger account (VPS plan — KVM 2 is the recommended starting point, roughly $100/year on an annual plan; promo code NATEHERK takes 10% off)
• GitHub account (free tier is fine)
• Telegram account
• OpenAI account with an active ChatGPT subscription ($20/month minimum)

Knowledge:

• You do not need to know Docker. The one-click install abstracts it entirely.
• You do not need to know terminal commands beyond copy-paste. Every command in this guide is exact.
• You do not need a Mac Mini or local machine running 24/7.

Time: 45–60 minutes for a first-time setup. Faster on subsequent agents.

One strong recommendation before you start: create a separate project in Claude Code (or any code editor) to store your VPS credentials, container names, API key references, and configuration notes. You will forget which container holds which agent within two weeks. A simple folder with an .env file and a README saves you hours of confusion later.

---

Deploying Hermes Agent: Step by Step

Step 1: Provision Your VPS

Go to Hostinger and select the KVM 2 plan. Choose a 12 or 24-month term — the monthly rate is meaningfully higher and you’re building infrastructure you’ll use long-term.

During setup, select Ubuntu 24.04 LTS as your OS. When you reach the apps screen, you’ll see Hermes Agent listed as an available one-click deploy. Do not select it here if you want the Docker container approach (which this guide uses). Leave the OS as plain Ubuntu and proceed.

Set a root password you’ll actually remember, or store it immediately in your credentials project. Enable the free malware scanner. Click finish.

The VPS takes 2–3 minutes to provision. While it’s spinning up, go to the dashboard and rename the hostname to something identifiable — youtube-hermes.vps or similar. This matters when you have multiple VPS instances and you’re trying to remember which is which.

Checkpoint: You have a running Ubuntu VPS with an IP address and root credentials.

Step 2: Launch the Docker Container

In your Hostinger VPS dashboard, navigate to the Docker manager. Click install, then go to one-click deploy. Search for “Hermes” and select it.

You’ll be prompted to set an admin username and password for the Hermes web interface. Copy both immediately into your credentials file. Click deploy.

The container spins up in under a minute. You’ll see a button to open the Hermes interface — that’s your entry point into the agent’s setup terminal. The main “Terminal” button in the Hostinger dashboard takes you to the root VPS, not inside the container. These are different things and the distinction matters when you’re managing API keys later.

Checkpoint: You have a running Hermes Docker container accessible via the Hostinger dashboard.

Step 3: Run Initial Setup and Connect Your Inference Provider

Click “Open” on the Hermes container. Enter your admin credentials. The onboarding wizard starts immediately.

When prompted to choose an inference provider, select OpenAI Codex. This routes inference through your ChatGPT subscription rather than API keys. You’ll be given a URL to visit — open it, sign into your ChatGPT account, authorize access, and copy the 9-digit code back into the terminal. Hit continue.

Select your model. GPT-5.5 is the current recommended option.

Checkpoint: Hermes is authenticated against your ChatGPT account and responding to prompts in the terminal.

Step 4: Create Your Telegram Bot

During setup, when prompted for a messaging channel, select Telegram.

Open Telegram and start a conversation with @BotFather. Send /newbot. Give it a name (e.g., “YouTube Hermes”) and a username (must be unique — add “bot” at the end if your preferred name is taken). BotFather returns a token. Copy it.

Paste the token into the Hermes setup terminal when prompted.

Next, you need your Telegram user ID. Message @userinfobot in Telegram — it replies with your numeric ID immediately. Paste that into the terminal when prompted for the allowed user ID. Confirm it as your home channel.

Checkpoint: Hermes is connected to a Telegram bot that only accepts messages from your account.

Step 5: Verify the Telegram Connection

Go to your new Telegram bot and send “hello.”

If nothing happens — no typing indicator, no response — go back to the Hermes terminal and describe what you’re seeing. The agent will diagnose the issue itself. In the most common failure case, the Hermes Gateway process has stopped; the agent will identify this, restart it, and confirm. Send “hello” again. You should see a typing indicator and a response.

This self-diagnosis behavior is worth noting: Hermes has skills for managing its own infrastructure. You don’t need to know what a gateway process is to fix it.

Checkpoint: You can send a message from Telegram and receive a response from Hermes.

Step 6: Add Your GitHub Token Securely

The right way to give Hermes an API key is not to paste it into the chat. Paste it into the chat and it lives in conversation history, which gets stored and potentially sent to inference providers.

The correct method: go to the Docker container terminal (the “Open” button, not the root VPS terminal), press Ctrl+C to exit the Hermes chat interface, and run:

hermes config set GITHUB_TOKEN <your-token>

This stores the token in /opt/data/.env inside the container — accessible to the agent’s tools but not in conversation history.

One important note on token type: fine-grained personal access tokens from GitHub do not have repo creation permissions by default. Use a classic token instead. When generating it, select the repo scope to allow both reading and writing. If you’ve already added a fine-grained token and need to replace it, use the nano command your agent provides to open the container’s .env file directly, delete the old entry, save with Ctrl+O then Ctrl+X, and inject the new token via hermes config set.

Checkpoint: Your GitHub token is stored in the container’s .env file and the agent can access it without it appearing in chat history.

Step 7: Create the Private GitHub Repo and Nightly Sync Cron

Back in Telegram, tell Hermes what you want:

“I just added my GitHub token to the env file — it’s called GITHUB_TOKEN. Please create a private GitHub repo for this agent. My GitHub username is [your username]. Once that’s done, set up a skill called ‘nightly GitHub sync’ and a cron job that runs it every night at midnight Central Time. Make sure it doesn’t push secrets.”

Hermes will locate the token, create the repo, push the initial state, and build the cron. Because the container runs in UTC, it will handle the timezone conversion by running the cron hourly and self-checking whether it’s midnight in your local timezone — a cleaner approach than a fixed UTC offset that breaks during daylight saving transitions.

The agent will ask for permission to create the repo and push files. Select “always allow” for repo operations so the nightly cron runs without prompting you at midnight.

When it’s done, you’ll get a link to the private repo. Click it. You’ll see your agent’s current state — memory files, skill definitions, configuration — committed and versioned.

Checkpoint: A private GitHub repo exists with your agent’s state, and a cron job will push updates to it every night at midnight your time.

---

The Failure Modes Worth Knowing About

“The Telegram bot isn’t responding after I set it up.” The Hermes Gateway process stops occasionally, especially after initial setup. Tell the agent what you’re seeing in the terminal chat. It will run diagnostic commands and restart the gateway. This is a one-time issue in most setups.

“I got an error about repo creation permissions.” You used a fine-grained token. Fine-grained tokens require you to explicitly select the target repo during creation — but the repo doesn’t exist yet, so you can’t select it. Use a classic token with the repo scope instead.

“I can’t find the .env file to delete my old token.” The .env file lives inside the Docker container at /opt/data/.env, not at the root VPS level. The nano command that works at root won’t work here. Ask Hermes for the exact command to open the container’s .env — it knows the path and will give you the correct nano invocation.

“The context window seems to be resetting mid-conversation.” Hermes auto-compacts at approximately 136,000 tokens. In Telegram, this is less visible than in the CLI — you won’t see a clear indicator. If the agent seems to have forgotten recent context, it likely compacted. This is expected behavior, not a bug. For long working sessions involving complex builds, the CLI interface gives you better visibility into context state. For scheduled tasks and on-the-go queries, Telegram is fine.

“A cron job I set up isn’t running.” Check whether the cron was created in a session that was itself a cron session. Cron sessions in Hermes cannot recursively create more cron jobs — this is a deliberate safety constraint. If you asked a cron to set up another cron, it won’t work. Create crons from a regular interactive session.

For Telegram-specific setup issues, the Claude Code Telegram channels guide covers some overlapping BotFather mechanics that apply here too.

---

Where to Take This Next

The setup above gives you a working agent with a nightly backup. That’s the foundation. Here’s what to build on top of it.

Expand the skill library. Hermes ships with 85 skills pre-installed. The community skills hub has 520+ more, including 16 official Anthropic skills covering canvas design, front-end design, and a skill creator that helps you build new skills. Drop a skill URL into Telegram and say “install this skill” — that’s the entire process.

Give the agent more context about you. Spend 10 minutes in Telegram telling it about your work, your goals, your team, what you don’t want it to do. It will write this into user.md and memory.md automatically. The more it knows, the less you repeat yourself.

Set up additional crons. The nightly GitHub sync is one example. Common patterns: morning briefings that pull from news sources, scheduled checks on external services, automated responses to incoming messages on a delay. Each one follows the same pattern: describe the outcome in natural language, let Hermes build the skill, confirm the cron schedule.

Consider the multi-agent question carefully. The decision tree for when to spin up a second Hermes agent: does the new workload need different API credentials? Separate long-term memory? Ongoing repeated work with a distinct audience? If yes to any of these, a new container makes sense. If no, keep it in your main agent. One agent doing too many things with too many API keys is a real failure mode — not because of technical limits, but because debugging becomes painful and the blast radius of any mistake grows. If you’re thinking about running multiple agents, the multi-agent setup patterns in Paperclip cover the orchestration logic that applies here too.

Think about what the agent should own. When you give Hermes access to external services — email, Slack, GitHub, whatever comes next — treat it like a new contractor. Give it its own accounts where possible, named API keys so you can track spend per agent, and scoped permissions rather than full access. The least-privilege rule applies to autonomous agents more than it applies to humans, because agents act faster and don’t second-guess themselves.

One thing worth considering as you build more of this infrastructure: the skills and memory files that Hermes manages are just markdown. That means they’re portable. If you ever want to build a production application on top of the workflows your agent is learning — something with a real database, auth, and a frontend — tools like Remy take a different approach: you write a spec in annotated markdown and it compiles into a complete TypeScript stack. The source of truth stays in prose; the code is derived output. The mental model isn’t far from how Hermes treats its own skill files.

The 85 pre-installed skills and the 520+ in the community hub cover a lot of ground. But the real value compounds over time — every skill Hermes writes from your workflows, every memory update from your corrections, every cron that runs while you’re not watching. The setup is an hour. The return on that hour extends as long as you keep using it.

If you want to explore agent infrastructure without writing orchestration code from scratch, MindStudio offers a no-code path: 200+ models, 1,000+ integrations, and a visual builder for chaining agents and workflows — useful if the VPS route feels like more infrastructure than your use case warrants.

The VPS approach gives you something different: full control, persistent state, and an agent that runs whether or not you’re at your desk. That’s worth an hour of setup.