Hermes personal AI assistant — a deployment guide

This is the version to keep open: a list of steps, commands, and values you come back to at every screen instead of relying on memory. I've ordered it the way you actually stand up an assistant — from an empty server, through the install, the model and the chat, to keys, your first automation, and upkeep. The five pillars of the theory (memory, skills, personality, crons, the self-improvement loop) get summarized up front only so the later commands make sense; everything after that is concrete, step by step.

Before you start: what you'll need

Gather this ahead of time so you don't stop mid-install:

• A server to run the assistant on. The most convenient option is a VPS — a rented cloud computer that runs continuously and that you manage remotely over SSH (you get an IP address and a password). Hermes also runs on a Mac Mini, a laptop, or Android via Termux, but this guide walks the VPS path because it's the easiest to repeat.
• Operating system: Ubuntu 24.04 LTS.
• An account with an AI model provider — the "brain" Hermes runs on. The cheapest sensible option without running a model locally is to connect an existing subscription (e.g. a ChatGPT/Codex plan at $20, $100, or $200 a month) instead of paying per request.
• A Telegram account (this guide uses Telegram as the example; Discord, Slack, WhatsApp, or iMessage work just as well).
• A GitHub account — you'll back up the assistant's memory and skills there.
• A separate email account for the assistant (a dedicated Gmail, say), not your personal one — you'll need it for tool logins.

What Hermes already ships with, so you don't have to add it: 91 built-in skills, access to a community library of over 520 skills (including 16 official Anthropic skills), image recognition, browser automation, image generation, speech synthesis, terminal commands, task scheduling, and voice replies (it can answer with an audio recording, not just text).

Five pillars glossary (read once, come back if unsure)

Without these five concepts, the commands that follow are just noise. With them, everything clicks into place.

• Memory — a small, persistent store the assistant carries between sessions. Every session starts with no memory (like the hero in Memento), so it loads two files: user.md (who you are, your style, what you can't stand) and memory.md (environments, projects, company context). Hermes updates these itself, but nudge it anyway: "save this to memory", "never do that again." You recover old conversations by searching sessions (Hermes keeps them in a SQLite database). Memory is not the place for secrets or temporary task status.
• Skills — procedural memory, ready-made instructions for "how to do this particular thing well" (like a recipe: pancakes come out the same every time from a recipe, but memory alone gives you a different result each time). Each skill is a skill.md file with a YAML header at the top telling the assistant what the skill does and when to use it. This is progressive disclosure: the full content loads only when it's needed, so it never clogs the context. Hermes can spot a repeated task on its own and turn it into a skill; skills improve with your feedback.
• Personality — the soul.md file sets the assistant's tone: terse, casual, formal, sarcastic — your call. It's plain markdown, no YAML header. It evolves over time as you correct it.
• Crons — scheduled, recurring tasks that turn the assistant from reactive into proactive while keeping the full agent loop intact. You say it in a plain sentence: "every day at 6am do X, Y, Z." Hermes creates the cron, wakes up in a fresh, separate session at the set time, does the task, and sends the result back to the original chat.
• The self-improvement loop — ties the other pillars together: you do the work, the assistant learns, you write the takeaways to memory, repeated steps become skills, the assistant searches past sessions when context matters, and the cycle continues. Automatic doesn't mean magic: the loop works best when you correct Hermes, tell it to save things to memory, and have it create and update skills after harder jobs.

Keep the simple axis in mind: memory = what to remember, skills = how to do it again.

Advanced cron parameters (useful once your automations get more complex):

• CONTEXTFROM — passes the output of one task into another.
• WORKDIR — runs tools from a specific project directory.
• the NOAGENT flag — runs the raw script without the agent's reasoning loop (script only, no agent layer).
• Cron sessions cannot recursively create further crons, so commands need to be self-contained.

Project context file — agents.md describes the goal and structure of an entire project for a scoped work environment (the equivalent of claude.md in Claude Code or AGENTS.md in Codex). It mainly matters when you use Hermes in the terminal for coding work.

Step 1 — Set up the VPS

1. Pick a power plan. Providers usually offer several tiers (e.g. KVM 1/2/4/8, differing in CPU, memory, and bandwidth). A mid-tier plan (KVM 2, say) is enough to start; you can scale it up later with one click, so don't overpay up front. An annual plan can be a good deal (roughly $100/year), and one VPS can host several assistants.
2. Set the configuration:

• OS: Ubuntu 24.04 LTS.
• If the provider offers a one-click Hermes deployment option, use it.
• Add a free malware scanner if one is available.
• Give it a memorable hostname (e.g. youtube-hermes.vps).
• Turn on daily automatic backups.

3. Save the access details somewhere secure right away: the admin username and password, the IP address, the hostname.

Step 2 — Choose an installation method

You have two paths:

• Root install — Hermes sits directly on the VPS, at the machine's top level. You run the install command in the provider's terminal.
• Docker container install — Hermes lives in an isolated "box" inside the VPS, usually stood up with one click through a Docker manager.

I recommend the container. It's the simplest, and it lets you later stand up several separate assistants on one VPS, each with its own keys, memory, and tools. Think of the VPS as an office building and each assistant as its own office with its own key.

Step 3 — Set up a project to manage your assistants (do this in parallel)

It looks like overkill at first, but in practice it's one of the more important things in the whole deployment. Set up a separate project in Claude Code that keeps watch over your servers and assistants.

Why:

• one tidy place for every VPS's configuration and access details;
• if an assistant goes down, Claude Code can log into the server and help rebuild it;
• you don't have to remember commands or terminal syntax;
• when something breaks, you just describe what you're seeing and get help talking it through.

What to save for each assistant:

• the admin username and password (in the project's .env file);
• the IP address and hostname;
• whether it's a Docker install or a root install;
• available tools, skills, file paths;
• notes on security and integrations.

Step 4 — Deploy the assistant (onboarding)

Once Hermes is deployed, open the chat (usually an "Open" button at the provider) and log in with the admin username and password you saved earlier.

4.1 Choose a model provider

There are many providers; the cheapest option outside of open source is usually connecting an existing subscription (ChatGPT/Codex, say) instead of paying per request. Log in through the link Hermes gives you, authorize access, copy the 9-digit code, and paste it into the terminal.

4.2 Choose a model

Pick the model with the best balance of capability and cost (with a connected Codex subscription, GPT-5.5 is often a sensible pick).

4.3 Connect Telegram

• In the setup wizard, select Telegram (spacebar) and confirm (enter).
• In Telegram, open BotFather and send /newbot.
• Give the bot a name and a unique username.
• Copy the bot's token (a string that proves the program is allowed to act on your behalf, something like an app password) and paste it into the VPS terminal.

4.4 Authorize your Telegram account

• In Telegram, find the USERINFO bot and message it to get your user ID.
• Paste the user ID into the terminal as the home channel's user.
• When asked whether this is the home channel, confirm "yes." That way, only you can talk to the assistant at first.

4.5 Save your configuration data

Hermes will show you which tools are available, the settings paths, where API keys live, and configuration paths. Copy all of it into your Claude Code project — it'll come in handy for troubleshooting later.

The single most important habit for this step. After connecting Telegram, you'll send a first "hi" and sometimes nothing comes back. Don't dig through code, and don't panic. Go back to Hermes in the terminal and describe the problem in a plain sentence: "I sent a message on Telegram and nothing came back." The assistant will look under the hood on its own, find the stalled service, restart it, and report that it's ready. Try again. The rule: you don't need to understand how everything works underneath, you need to be able to clearly describe what you see and what isn't working.

Once the connection works, spend five to ten minutes telling the assistant about yourself: your goals, what you're working on, who's on the team, which processes you plan to hand off over time. In the background, it's building its memory files.

Step 5 — Connect a private GitHub repository

This is the first thing every new assistant should do. If the VPS breaks, memory, skills, and configuration are safely stored outside it — you stand up a new Hermes, connect the repository, and nothing is lost.

5.1 Run the setup

Tell Hermes: "Set this up as a private GitHub repository. Look into it and figure out how it works." Hermes has built-in skills for repository management and GitHub authorization. It will ask you for your GitHub username, the repository name, commit identity, and a personal access token. It creates a .gitignore on its own, so secrets never land in the repository even with a private setting.

5.2 Generate a personal access token (PAT)

• In GitHub: Settings → Developer settings → Personal access tokens.
• Try a fine-grained token with contents: read/write permission first.
• If that's not enough (no rights to create repositories), generate a classic token with full repo scope.
• Set the token's expiry to match the use case: 30 days for testing, longer for a permanent deployment.

5.3 Store the key safely (the key rule)

Never paste the token into the chat itself — it would sit in the chat history forever. Use Hermes's configuration command instead:

1. On the VPS, open the chat ("Open" button), then hit Ctrl+C to exit Hermes's chat into the Docker shell.
2. Run:

hermes config set GITHUB_TOKEN <paste-token-here>

3. This saves the token to the /opt/data/.env file inside the Docker container, never to the chat log.
4. Tell Hermes: "The new token is in the .env file as GITHUB_TOKEN." The assistant will read it.

The same rule applies to every key, no exceptions.

5.4 Edit or delete the key

If you need to remove or update a key, ask Hermes for the nano command that opens the .env file. Make sure you're editing the .env inside the Docker container, not the VPS root's .env. In nano, save with Ctrl+O and Enter, exit with Ctrl+X. If nano isn't installed, ask Hermes to install it or suggest an alternative editing command.

Step 6 — First skill and first cron (nightly GitHub backup)

Once GitHub is connected, set up a daily backup cron. Just say: "Every night at midnight my time, push changes to this repository. Build a skill around that."

What Hermes does under the hood:

• reviews existing, related skills;
• runs terminal commands to set up the cron;
• creates a new skill (e.g. nightly-github-sync);
• updates memory.md with the new context;
• handles the time zone difference itself (the container runs in UTC, but Hermes checks your time zone so a time change doesn't throw the schedule off).

Permission levels in Telegram. When Hermes wants to run a command, it asks: allow once, allow for the session, or always allow. For repeated, trusted actions, like a commit to the repository, choose "always allow" so the cron runs without prompting.

Two ways to build a skill:

1. Describe the outcome you want in plain language and let Hermes build it.
2. Install a ready-made one from the library: copy the skill's URL, paste it to Hermes, and say: "Install this skill and run it."

Step 7 — Know when to use the terminal vs Telegram

Both interfaces run the same agent — Telegram does not run a weaker version. The difference is in visibility and control.

The terminal (CLI) is the cockpit:

• best for deep work, building, coding, "living" in the agent;
• better visibility into the context window;
• every slash command is available;
• use it when you're at your computer for high-risk tasks.

Telegram is the remote control:

• best for scheduled tasks, quick checks, work on the go;
• less visibility into the context window and session state;
• automatic context compaction happens under the hood as you approach the token limit;
• don't run high-stakes work from Telegram, keep it to low-risk tasks.

Context is measured in tokens, not messages. The model always sees the system prompt, user.md, personality, and so on. As you near the window limit, Hermes triggers automatic compaction. In Telegram you can't see exactly when that happens, so high-stakes work is riskier there.

Step 8 — Security and key hygiene

Treat Hermes like a new hire or an intern. You wouldn't hand a new employee your credit card — treat this the same way.

Accounts and keys:

• give each assistant its own email account (Gmail or AgentMail), not your personal one;
• if you have to share a key, use one with a very narrow scope;
• use named API keys per assistant (separate OpenRouter or Perplexity keys, say) so you can track spend on each one individually;
• apply the principle of least privilege: only the credentials and tools needed for that role.

Hardening the VPS:

• set a firewall at the provider;
• restrict access to your IP and close unused ports;
• ask Hermes or Claude Code to survey the environment and recommend a firewall configuration;
• build a nightly or weekly security-audit skill that checks for vulnerabilities.

Step 9 — Ongoing maintenance

Hermes is never "done being configured" — it's a coworker you keep guiding and teaching.

• When the assistant makes the same mistake twice, correct it on the spot and have it update the relevant skill or memory.
• When you give the same instruction twice, ask Hermes to turn it into a skill.
• When it talks too much or in the wrong tone, correct soul.md.
• When you want a new recurring task, build a skill and ask for a cron to be set up.
• When something breaks, check memory.md first. Stale memory is the most common cause of odd behavior.
• At any point you can ask: "Read me your memory file" or "Read me your personality file" to see what's actually in there.

Step 10 — Scaling: one assistant or several

As things grow, you may want separate assistants for different roles. Don't force it, use one assistant until you naturally hit the criteria below.

How to split assistants across one VPS:

• each assistant runs in its own Docker container;
• each container has its own memory, tools, and private API keys;
• containers don't share .env files, so keys never mix.

Decision tree for a new assistant — spin up a new one if you answer "yes" even once:

• Does it need different permissions, secrets, or tools?
• Does it need its own long-term memory?
• Is this ongoing or recurring work (not a one-off)?

If it's "no" across the board, keep it inside your main, personal Hermes.

A bad pattern versus a good one:

• Bad: one mega-agent with every key, every skill, and every cron, a lot of tangle and high risk when it breaks.
• Good: split by vertical (marketing, finance, operations) or by platform/role, cleaner memory, easier diagnosis, lower risk.
• Migration is easy, because skills, memory, and crons are just plain markdown files, you move them between assistants as needed.

Appendix — Hermes dashboard (optional)

Hermes has a built-in dashboard: recent sessions, connected platforms, a Kanban board, keys, configurations, skills, and plugins.

How to open it: tell Hermes you want to open the dashboard, and give it the VPS route and the Docker container configuration. Hermes will open a gateway and a tunnel so you can reach the local dashboard. The first attempt is often clunky; once it works, save it as a skill so opening it next time comes down to "open the dashboard" and three commands.

When it's useful: with several assistants working on different projects (the Kanban view), for visualizing tasks across assistants, as a quick way to manage crons, plugins, and configurations. If you mainly work on the go through Telegram, you'll rarely need it.

Final cheat sheet

• Hermes is at its best for on-the-go automation through Telegram. For desk-bound thinking work, Claude Code stays the first choice.
• The five pillars (memory, skills, personality, crons, the self-improvement loop) are the mental model for everything Hermes does.
• Run the Docker container install on Ubuntu 24.04 LTS.
• Always set up a Claude Code project to manage your servers (passwords, IPs, configurations). It pays for itself the first time something breaks.
• The first thing after deployment: connect a private GitHub repository and set up a daily backup cron.
• Never paste API keys into the chat, use hermes config set KEY_NAME <value> from inside the Docker container.
• Treat every Hermes like a new hire: least privilege, named keys per assistant, separate accounts wherever possible.
• A stale memory.md is the most common cause of odd behavior, check it first when something's off.

And one last thing, because it's what decides whether this works: someone else's use case isn't yours. Before you start, answer for yourself which specific repeatable job you want off your plate, and set your first cron for exactly that one.