~9m59:20Hermes Agent - Full Course & Setup Guide - For COMPLETE Beginners
Jun 5, 2026
Read: ~9m · You save: 50 min
Hermes Agent - Full Course & Setup Guide - For COMPLETE Beginners
Set up Hermes Agent, a self-learning AI assistant that runs 24/7 on a VPS. Covers deployment, Telegram, GitHub backups, Gmail and Calendar integration, and automations.
Overview
Hermes Agent is a personal AI assistant. It runs continuously, executes tasks in the background, and performs actions beyond text generation. It can write reports, research topics, draft emails, review calendars, compile daily digests, and search the web.
This guide covers the fundamentals of setting up Hermes Agent, configuring it, and building practical workflows. It assumes no prior experience.
Hermes Agent runs on a virtual private server (VPS), so it operates 24/7 without physical hardware that must stay powered on and connected.
Key Differences from Other Agent Frameworks
Hermes Agent is compatible with OpenClaw and other agent frameworks, but it differs in one main respect: it includes a self-learning loop. As the user works with the agent, it stores information about the user, refines its behavior, and builds skills automatically. The agent improves over time.
Hermes Agent is designed for consistent, multi-task use across a user's daily life. For a single, fixed automation, a dedicated tool such as OpenClaw, Claude Code, or a simple no-code workflow is a better fit.
Hermes Agent works with any large language model (LLM), including those from OpenAI, MiniMax, and Anthropic. Users do not need to write code. They can communicate in English or any other language, and they can dictate instructions instead of typing.
Core Components
Hermes Agent consists of five core components:
- Memory
- Skills
- Soul
- Crons (scheduled tasks)
- Self-improvement loop
Memory
An LLM predicts text: it receives input text and returns output text. Hermes Agent surrounds the LLM with software that manages context. This software supplies the information the model receives, provides tools such as a browser or a code executor, and manages memory and sessions.
After installation, the directory contains markdown files, configuration values, environment variables for secrets and API keys, and a memory folder. The memory folder contains at least two files:
- user.md stores information about the user, such as name, age, location, and preferences.
- memory.md stores long-term facts that the agent considers important to retain.
Hermes Agent updates these files automatically. Users do not need to edit them directly.
Skills
A skill is a repeatable workflow, stored as a markdown file. It may include scripts or other files. Each skill describes its purpose, when to use it, and the steps to follow.
Hermes Agent includes approximately 90 built-in skills and offers more than 500 community skills for installation. Users can also create their own skills.
Skills use progressive disclosure. At startup, the agent loads only the name and description of each skill. It loads the full instructions only when a task requires them. This reduces memory use and token consumption.
Soul
The soul is a markdown file that defines the agent's behavior, such as tone, style, and personality. Users can describe the desired behavior directly or instruct the agent to adjust its soul.
Automations and Scheduled Tasks
Hermes Agent can run tasks on a schedule, for example every day, hour, week, or month. Reactive agents wait for instructions. Proactive agents work in the background. Scheduled tasks make Hermes Agent proactive.
Self-Improvement Loop
The agent reviews completed work, saves relevant information to memory, and creates skills automatically when a user repeats a request. It does not require a manual instruction to do so.
Security Considerations
Autonomous agents can take actions that cause harm. Treat Hermes Agent like a new team member: grant access gradually, starting with minimal permissions.
The main risks are:
- Uncontrolled spending. Without spending limits on an API key, the agent can incur costs of hundreds of dollars per day. Giving the agent access to a payment card allows it to make purchases.
- Prompt injection. Anyone who can message the bot can send it instructions. Hidden instructions in content the agent reads, such as an email, can also trigger unintended actions.
- Data leaks. An exposed agent can allow an attacker to obtain the API key or access sensitive files.
- Destructive actions. The agent may delete files, send emails, or make payments that it should not.
Protective Measures
- Use named, separate API keys. Create one API key per tool. This allows revocation, rotation, or remote lockout without affecting other tools.
- Apply least privilege. Grant only the permissions the agent needs. Do not grant administrator access.
- Start in read-only mode. Read-only access carries far less risk than permission to edit, modify, delete, or send.
- Create dedicated accounts. For email-heavy tasks, give the agent its own email address.
- Never share secrets in chat. Set keys with a command in the terminal, as described below.
- Rotate keys regularly.
- Back up the configuration to a private GitHub repository.
- Harden the server. Ensure that unauthorized users cannot reach the agent over the internet.
Setup Procedure
Step 1: Deploy a Virtual Private Server
A VPS is a cloud-hosted computer in a secure data center. Compared with a physical device, a VPS:
- costs less, especially on a monthly basis;
- runs continuously without depending on a local device staying on, connected, or secure;
- can be stopped or terminated with one action if a security breach occurs.
A dedicated Mac Mini is an alternative. It costs more, and it must be physically secured. Anyone who steals it gains unrestricted access to the agent.
The example in this guide uses Hostinger, which offers a one-click Hermes Agent deployment. The recommended plan is KVM2, which costs $9 per month. The discount code "techwithtim" provides an additional 10% off the selected term.
Hostinger deploys the agent in a Docker container, an isolated and hardened environment. On the deployment page, copy the admin password. It is required for sign-in. The page also displays a Nexos API key, which provides free AI credits and is not required for the setup.
To use other hardware or a server, run the curl command from the Hermes Agent website, then run the hermes setup command. The remaining steps are identical.
Step 2: Access the Dashboard
- Wait until the Hermes Agent container status changes from "created" to "running." To find it, open the VPS, then the Docker Manager tab.
- Select Open.
- Sign in with the username
hermes(lowercase, the default) and the admin password.
To retrieve the password later, open Docker Manager, select Manage, and check the Environment section. Change the password there if it is exposed. Do not share it. The Overview tab allows the VPS to be stopped or rebooted. Changing the root password is required for SSH access, which this guide does not use.
Step 3: Run the Full Setup
Navigate the terminal with the arrow keys. Select with Enter or Space. The terminal does not support the mouse.
Select the AI provider. Hostinger defaults to Nexos AI. This guide uses OpenAI. Do not use a Claude Code subscription, because it is billed as extra usage. Use an OpenAI plan if one is available. Open the provided URL, sign in, enter the code, and continue.
Select the model. This guide uses GPT-5.5. Multiple models and providers can be configured, but one provider is sufficient for most users.
Select the text-to-speech provider. Keep the default, Edge TTS. ElevenLabs offers more human-sounding voices.
Select the terminal backend. Keep the local terminal backend.
Set the maximum number of iterations. An iteration is one call to the LLM within a single task. The default is 90. Higher values allow longer, deeper tasks. Most users do not need more than 90.
Set the tool progress mode. The options are:
- Off: shows only the result.
- New: reports each tool the first time it is used.
- All: reports most actions. This is the default and recommended option.
- Verbose: reports all actions with additional detail.
Set context compression to 0.8. The context window is the maximum amount of information a model can hold at one time. The value sets the point at which the agent compresses the conversation. At 0.5, compression starts when the context is 50% full. At 0.8, compression starts at 80%, which preserves more information for longer.
Set the session reset mode to inactivity plus daily reset. A session is a conversation. Sessions on different platforms are separate and do not share information. With this setting, the session clears after a period of inactivity and resets daily. Important memories are saved automatically. Keeping the context window small also reduces cost. Keep the default timeout and reset hour.
Configure a messaging platform. Telegram is the simplest option to start with. Slack is more useful for business tasks. Select Telegram, press Space to enable it, then press Enter.
Creating the Telegram Bot
- Create a Telegram account and install the application on the device to be used.
- Search for BotFather. Select the account with the blue verification check mark.
- Send
/newbot. - Enter a display name, such as "Hermes Agent."
- Enter a username. It must be unique and end in
bot, in lowercase, such ashermesagent32456_bot. - Copy the token that BotFather returns. Do not share it. Anyone with the token can message the bot.
- Paste the token into the setup prompt.
Restricting Access
Only approved users should be able to message the bot.
- In Telegram, search for userinfo.
- Send
/start. The response displays your user ID. - Paste the ID into the setup prompt. To allow several users, separate their IDs with commas. Each user must run the same command to obtain their own ID.
- Confirm the prompt to use the ID as the home channel.
Configure tools. No action is required. The prompt shows the built-in tools.
Configure the browser provider. Two options exist:
- Local browser: free. It is a headless browser, which cannot render complex JavaScript or view pages visually. It retrieves the HTML of a page. It suits basic searches and simple operations.
- Browserbase or Firecrawl: paid services, typically about $20 per month, with free initial credits. They provide a full remote browser in the cloud, which the agent can control. Multiple browser windows can run at once, requests can come from different regions, and some captchas can be bypassed.
This guide uses the local browser.
Configure image generation. Select OpenAI Codex, then the image model "image 2 medium."
Configure text-to-speech. Keep the default free option.
Configure search. Keep Firecrawl. The self-hosted open-source version is free. The paid version requires a Firecrawl account. Search and browser automation are separate functions. Search retrieves web results. Browser automation controls a browser. Firecrawl does not provide browser automation.
Firecrawl instance URL. Press Enter to accept the default.
After completing the Telegram tool configuration, press Enter to reconnect. Setup is complete.
Step 4: Test the Agent
- Enter "hello world" in the terminal user interface (TUI). The TUI is the default chat interface.
- To reopen the TUI after exiting, type
hermesin the terminal. Press Control+C to quit. - To return to setup, run
hermes setup. - To test Telegram, open the bot link from BotFather, select Start, and send a message. The bot should display "typing" and respond.
If the bot does not respond, ask Hermes Agent to diagnose the problem. Describe the symptom: Telegram is connected, the message shows a received check mark, but the bot does not type or respond. In the demonstration, the agent found that the Hermes gateway had stopped. It restarted the gateway, verified the connection, and resolved the issue.
Initial Configuration
Profile and Behavior
Provide the agent with a description of the user: name, role, goals, and preferred behavior. Then ask the agent to update its soul file. Example elements to include:
- the user's name and how the agent should address the user;
- the user's background and goals;
- the desired tone, such as concise, direct, and educational;
- an instruction to avoid filler and to explain the reasoning and steps behind actions.
The agent saves these preferences and updates its files.
Automated Backups with GitHub
GitHub is a version control service. It records changes to files, so any earlier version can be restored. A backup protects the agent's memories, conversations, skills, and files if the server fails.
Creating the Repository
- Create a free GitHub account if you do not have one.
- Select New repository.
- Name it, such as
hermes-agent-backup. - Set visibility to Private. This setting is required.
- Select Create repository.
Creating a Fine-Grained Token
Create a token that can access only this repository.
- Open GitHub Settings, scroll down, and select Developer settings.
- Select Personal access tokens, then Fine-grained tokens.
- Select Generate new token.
- Enter a name, such as "Hermes backup repo."
- Set expiration to No expiration, or choose a limit.
- Under repository access, select Only select repositories, then choose the backup repository.
- Under permissions, select Add permissions, then Contents. Set the access level to Read and write.
- Select Generate token and copy the token.
Storing the Token Securely
Do not paste the token into the chat. Chat messages are stored in session logs and sent to the LLM provider. Set the token from the terminal:
hermes config set GITHUB_TOKEN <your-token>
The command stores the value in a secret environment file that is not exposed to the agent's chat. Use this method for every secret key, API key, or credential. Delete the token from your records after setup.
Running the First Backup
- Restart the TUI with
hermes. - Give the agent the repository URL and the token access, and ask it to back up the current configuration and state without saving secrets, credentials, or sensitive data.
- Approve the command when prompted. Selecting "always" is appropriate for repository cloning and setup commands.
- Refresh the repository page. It should contain folders for skills, state, memories, cron, and config, plus files such as
user.mdandmemory.md.
Review the repository for sensitive data. If any appears, instruct the agent to remove it.
Enabling Continuous Backups
Instruct the agent to commit and push to GitHub after every significant change. Each commit creates a checkpoint. If performance declines after a change, the agent can revert to an earlier version.
Voice, Images, and Browser Automation
Voice. Send a voice message to test speech-to-text. The agent transcribes the message and describes it. Ask it to send a voice reply to test text-to-speech. Under the default settings, both work.
Images. Attach one or more images if the model supports image input. Most current models do.
Browser automation. Ask the agent to open a website, take a screenshot, and describe the page. The first attempt may fail with a message that the browser runtime or agent browser is not installed. Ask the agent to install the agent browser, then retry. After installation, the agent can perform basic web automation.
Connecting External Tools with Composio
Composio connects the agent to external accounts through one integration. Connections such as Gmail, Google Calendar, GitHub, Slack, and Notion are managed in the Composio dashboard. The free tier includes approximately 20,000 tool calls per month. The agent can take action in each connected account only after the connection is established.
Connection Procedure
- Create a free account at dashboard.composio.dev.
- Open Connect apps and select the applications to connect. Use a dedicated account where possible. Multiple accounts can be connected.
- Review the permissions. Composio allows the available tools to be restricted later.
- Open Install and select the OpenClaw instructions. Copy them and provide them to Hermes Agent, asking it to follow the instructions and connect to Composio.
- Open the authorization URL, approve the request, and return to the agent. The agent confirms the connection.
- If an application shows as not linked, select the link the agent provides and complete the authorization.
Once connected, the agent can run actions such as reading the most recent emails or creating a calendar event. Early in use, the agent may choose the wrong skill, such as a Google Workspace skill instead of a Composio skill. Instruct it to use Composio for those tasks.
Grant the agent the least access needed. Start with read-only access.
Workflow Examples
Daily Email Triage
Ask the agent to run a scheduled task every day at 7:00 a.m. It reviews the emails from the previous 24 hours, identifies action items, and sends a concise summary to the chat. Adjust the format through feedback. The agent records these preferences and updates its skill.
The scheduled task is stored in the cron configuration file (jobs.json). Each run is also backed up to GitHub.
Weekly Security Audit
Ask the agent to run a security audit every Sunday at 12:00 a.m. It checks the VPS for unusual activity and sends a report with suggested improvements.
Other Common Use Cases
- Morning briefing or digest: The agent gathers information from connected sources and lists the key action items.
- Calendar management: The agent reviews the calendar and schedules blocks for workouts, meals, or focused work.
- Automated accounting: When a new email contains a receipt, the agent uploads it to a Google Drive receipts folder.
- Daily wrap-up: At the end of each day, the agent summarizes completed work and proposes improvements for the next day.
- Learning routines: For example, the agent sends five new Indonesian words each day, quizzes the user, and requests a spoken answer.
The value of Hermes Agent depends on the integrations connected and the tasks the user defines. It is not a substitute for a defined workflow, and it does not produce results automatically. Its usefulness increases with consistent use.
Introduction and What Hermes Agent Is
Hermes Agent is a personal AI assistant that runs continuously, takes actions rather than only chatting, and improves over time through a self-learning loop.
- Hermes Agent is described as a personal AI assistant that can run 24/7 in the background, typically on a virtual private server.
- It can manage email, calendar, daily digests, web search, and research.
- It is not just a chatbot; it can write reports, research, draft emails, and review calendars.
- Compared with OpenClaw, Hermes Agent has a self-learning loop, which the speaker cites as the reason for its popularity.
- Hermes Agent is meant for ongoing, multi-task use; for a single simple automation, OpenClaw, Claude Code, or a simple no-code workflow is suggested.
- It can work with any LLM, such as OpenAI, MiniMax, or Anthropic models.
- Users do not need to write code; they can speak or dictate instructions in English or other languages.
Core Concepts: Memory, Skills, Soul, Automations, and Self-Improvement
Hermes Agent consists of five core concepts: memory, skills, soul, crons (scheduled tasks), and the self-improvement loop. The software wraps an LLM, managing context, tools, and memory.
- The five core concepts are memory, skills, soul, crons/scheduled tasks, and the self-improvement loop.
- The LLM is the brain that only predicts text; Hermes Agent software manages context, tools (e.g., browser, code execution), and memory around it.
- Installation creates a directory with markdown files, configuration values, environment variables for secrets/API keys, and a memory folder.
- The memory folder contains user.md (information about the user such as name, age, location, preferences) and memory.md (long-term facts the agent considers important).
- Skills are markdown files, sometimes with scripts, describing what a skill is, when to use it, and step-by-step instructions.
- Hermes Agent includes about 90 built-in skills and over 500 community skills that can be installed; users can also create their own.
- Skills use progressive disclosure: only name and description load at startup; full instructions load when needed, saving tokens.
- The soul is a markdown file describing the agent's personality and behavior, editable by simply asking the agent.
- Automations/crons run tasks on a schedule, making the agent proactive instead of reactive.
- The self-improvement loop lets the agent review user interactions, save information to memory, and build skills automatically.
Security Disclosure and Guardrails
Because agents have autonomy, treat them like a new team member: restrict access, grant permissions gradually, and set safeguards against spending, prompt injection, data leaks, and destructive actions.
- Risks include uncontrolled spending (e.g., hundreds of dollars per day via an API key without limits) and giving the agent a credit card.
- Prompt injection can occur when the agent is open to anyone or when hidden instructions in content such as an email trigger unintended actions.
- Data leaks can occur if the agent is exposed on the internet, risking API keys and sensitive files.
- Destructive actions include deleting Google Drive files, sending incorrect emails, or making unauthorized payments.
- Recommended safeguards: give the agent its own email address, use one API key per tool so keys can be rotated or deleted, grant least-privilege access, and start with read-only mode.
- Never paste API keys directly into the chat; set secrets using the command line instead.
- Rotate keys regularly, back up the agent in a private GitHub repo, and harden the server so it is not publicly accessible.
Deploying Hermes Agent on a Hostinger VPS
The speaker deploys Hermes Agent on a Hostinger VPS using one-click Docker deployment, choosing the KVM2 plan (about $9 per month), and retrieves the admin password from the environment settings.
- Recommended plan is Hostinger KVM2 at $9 per month; a discount code 'techwithtim' gives an additional 10% off (as spoken in the video: 'tech with Tim').
- Deployment installs Hermes Agent in a Docker container for a hardened environment.
- A VPS is a cloud computer in a data center, cheaper than hardware and running 24/7; a Mac Mini alternative is more expensive and requires physical security.
- The admin password appears on the deployment page; the Nexos API key is a free provider credit and can be ignored.
- Wait until the Hermes agent container status shows 'running' in the Docker Manager tab, then click Open.
- Sign in with username 'hermes' (lowercase) and the admin password.
- The admin password can be viewed or changed in Docker Manager under Manage, then Environment.
- The overview tab allows stopping or rebooting the VPS.
- Non-Hostinger users can install Hermes via the curl command from the Hermes agent website and then run the Hermes setup command.
Full Setup Walkthrough
The full CLI setup configures the AI provider (OpenAI Codex with GPT 5.5), text-to-speech, terminal backend, iteration limits, tool progress mode, context compression, session reset, Telegram messaging, browser and search tools, and image generation.
- Setup is navigated with arrow keys, enter, and space; the terminal does not accept mouse input.
- The default provider is Nexos AI; the speaker switches to OpenAI Codex with an OpenAI subscription, and advises against using a Claude Code subscription because it now bills as extra usage.
- Authentication involves opening a URL, signing in with email, and pasting a code.
- The model selected is GPT 5.5; multiple models can be configured for cost optimization.
- Text-to-speech default is Edge TTS (free); ElevenLabs is an alternative.
- Terminal backend stays on local.
- Maximum iterations default is 90 (number of LLM calls per task); 150+ is possible but usually unnecessary.
- Tool progress mode options are off, new, all, and verbose; 'all' is recommended.
- Context compression is set to 0.8 so the context window is compressed when about 80% full, rather than 0.5.
- Session reset mode is set to inactivity plus daily reset, with default timeout and reset hour.
- Telegram is configured as the messaging platform because it is the easiest to start with.
- Browser provider: local headless browser is used by default; Browserbase or Firecrawl are paid, more capable cloud options (around $20 per month mentioned).
- Image generation uses OpenAI Codex with the image 2 medium option.
- Text-to-speech stays on default free option; search provider uses the self-hosted open-source Firecrawl option.
- Running 'hermes' reopens the TUI; Ctrl+C quits; 'hermes setup' returns to setup.
Connecting Telegram
Telegram is connected by creating a bot with BotFather, copying the bot token, and restricting access to specific user IDs obtained via the user info bot.
- Search for BotFather with the blue check mark in Telegram, then type /newbot.
- Provide a display name (e.g., Hermes Agent) and a unique username ending in 'bot' (lowercase).
- Copy the bot token and keep it private; anyone with it can message the bot.
- Restrict access by obtaining your user ID: search for 'userinfo' in Telegram, send /start, and copy the ID.
- Multiple user IDs can be separated by commas.
- When testing failed, the speaker asked the Hermes agent to debug; it restarted the gateway and fixed the connection.
- Voice dictation tool Whisper Flow was mentioned by the speaker, a sponsored-style mention to be excluded from the summary.
Onboarding, Soul, and Automated GitHub Backup
The agent is customized through an onboarding prompt that defines the user's identity, goals, and the desired soul (concise, direct, educational), then backed up to a private GitHub repository using a fine-grained personal access token set via the CLI.
- Onboarding prompt provides name, role, audience, goals, and desired behavior; the agent updates soul.md accordingly.
- A private GitHub repository named 'Hermes agent backup tutorial' is created with visibility set to Private.
- A fine-grained personal access token is generated with no expiration, access limited to the single repository, and Contents permission set to read and write.
- The token is set with the command: hermes config set GITHUB_TOKEN followed by the token value, which is stored in a secret environment file rather than the chat.
- The agent clones the repo and backs up configuration and state (skills, state, memories, cron, config) without secrets.
- The speaker recommends reviewing the repo for sensitive files.
- The agent is prompted to commit to GitHub after every significant change, enabling version history and rollbacks.
- Commits and jobs.json files can be inspected to view history and cron tasks.
Voice, Images, Browser Automation, and Composio Integration
Voice input and output, image uploads, and browser automation are tested; Composio is connected to Gmail and Google Calendar to let the agent take real actions.
- Voice works by default with speech-to-text and text-to-speech; the agent can send voice messages.
- Images can be uploaded to image-enabled models such as GPT or Opus.
- Browser automation may initially fail with 'Chrome isn't installed for the browser tool'; the fix is to ask the agent to install agent-browser.
- A test prompt asked the agent to visit techwithtim.net, take a screenshot, and describe the page.
- Composio (dashboard.composio.dev) is a free tool (about 20,000 tool calls per month) that connects the agent to many apps through one connection; the speaker says it is not sponsored.
- Gmail and Google Calendar were connected via the Composio dashboard; the install instructions for OpenClaw were pasted into Hermes to connect Composio.
- Authorization requires opening a URL in the browser and clicking authorize.
- Example commands: list the last two emails in the inbox, create calendar events, read Slack messages.
Practical Use Cases and Automations
Example automations include a daily 7 a.m. email triage, a Sunday security audit of the VPS, and other workflows such as morning briefs, calendar optimization, automated receipt accounting, daily wrap-ups, and habit tracking.
- Daily email triage: every day at 7:00 a.m., summarize action items from the past 24 hours' emails and send them to the chat.
- The triage job is stored in cron jobs.json; the speaker mentions a 9:00 a.m. run in the transcript, while the prompt specified 7:00 a.m.
- Weekly security audit: every Sunday, check the VPS for unusual activity and send a report with improvement suggestions.
- Other ideas: morning brief or digest, calendar scheduling for workouts and focus blocks, automated accounting that uploads receipts to a Google Drive receipts folder, and a daily wrap-up of achievements and improvements.
- Habit tracker example: teach five new Indonesian words each day, quiz the user, and request voice responses.
- The speaker says the tool is not a get-rich-quick solution but is useful when configured correctly.