Hermes Agent for beginners: set up and complete your first task

Hermes has done more than suggest a meeting checklist. The agent created meeting-checklist.md, read the saved file back, and returned a verification summary: the file exists, all five items are there, and no unexpected files are present in the demo folder.

A personal AI agent is an AI assistant that can use the tools and permissions you give it to perform work and show what was completed. Hermes can run directly in your terminal. Gateway and Telegram are optional additions when you want to reach the same agent from your phone.

What you will complete in one beginner session

• Install Hermes through the current official path for your computer.
• Choose a model and confirm that a normal chat works.
• Create one file in an empty demo folder and review the agent's receipt.

Telegram comes last and is entirely optional. Get the terminal workflow working first.

Before you start

You need a supported platform, access to a terminal or PowerShell, and a model provider that Hermes can use. The installer requires Git on every non-Windows platform; Linux also requires curl and xz-utils. It handles dependencies including Python, Node.js, ripgrep, and FFmpeg. macOS is currently supported on Apple Silicon, not Intel-based Macs.

Start in an empty hermes-demo folder rather than among customer files or an active project. That makes the task and its boundary easy to inspect.

Sources: Installation, Platform Support, and Quick-start.

Install Hermes Agent

On Apple Silicon Macs and Windows, Nous Research recommends the Hermes Desktop installer. It also installs the command-line tool.

For Linux, Apple Silicon macOS with CLI only, or WSL2, run:

curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash

For a native Windows CLI installation, run this in PowerShell:

iex (irm https://hermes-agent.nousresearch.com/install.ps1)

Reload your shell after a Unix-like installation, then check the version:

source ~/.bashrc   # or source ~/.zshrc
hermes --version

Do not rely on older pip, Homebrew, or AUR instructions. The current Platform Support page lists the supported installation methods.

Choose a model and verify the chat works

Run the complete setup wizard:

hermes setup

Use hermes setup as the main path. If Hermes is already configured, use the following command when you only want to change provider or model:

hermes model

Hermes supports several authentication paths, including OAuth, API keys, and compatible custom endpoints. Choose a provider you already use and follow its current setup flow. According to the current documentation, the model needs a context window of at least 64,000 tokens. Never put an API key in a chat prompt or screenshot.

If you have a Nous Portal subscription, there is also a fast OAuth path that configures the provider and Tool Gateway:

hermes setup --portal

Then start Hermes:

hermes

hermes --tui opens the newer terminal interface. Continue only when the selected model appears, Hermes replies without an authentication error, and one follow-up message works. Also confirm in the welcome information or with /tools that File Operations and Terminal are available. If either is missing, exit with /quit, run hermes tools in the terminal, enable them, and start a new session.

When both replies work, leave that chat session open and start a new terminal window for the next step. Do not paste the commands below into Hermes chat.

Sources: AI Providers and Hermes Quick-start.

Create a dedicated demo folder

On Linux, macOS, or WSL2:

DEMO_DIR="$(mktemp -d "$HOME/hermes-demo-XXXXXXXX")"
cd "$DEMO_DIR"
hermes

In Windows PowerShell:

$DemoDir = Join-Path $HOME ("hermes-demo-" + [guid]::NewGuid().ToString("N"))
New-Item -ItemType Directory -Path $DemoDir | Out-Null
Set-Location $DemoDir
hermes

The empty folder makes it easy to see whether Hermes stayed within the task.

Create your first verified file

Paste this task into Hermes:

Create meeting-checklist.md in the current folder with a clear title and exactly five checkbox items for preparing a 30-minute team meeting. Use the available file and terminal tools to confirm that the file exists, then read back the saved content. Finish with a short verification summary showing the absolute path, the checkbox count, the first item, and that no additional files are present in the demo folder. Do not create any other files in the demo folder.

Review the action Hermes wants to perform before approving it. The task should remain inside the demo folder and create only one file.

How to confirm the task really finished

A useful final receipt looks like this:

File: /home/yourname/hermes-demo-a1b2c3d4/meeting-checklist.md
Exists: yes
Checkboxes: 5/5
First item: Write the meeting goal in one sentence.
Additional files in demo folder: none

The distinction matters. A written chat response can describe a file that has not been saved. The summary should come from the file Hermes actually created and read back, plus a check of the demo folder contents.

If something is missing, ask Hermes to rerun only the failed verification. Use hermes doctor for installation problems, hermes model for model or authentication errors, and reload your shell if the hermes command is not found.

Optional: reach Hermes from your phone with Telegram

Once the terminal path works, you can add Telegram:

1. Create a bot through the official @BotFather using /newbot.
2. Keep the bot token secret and find your numeric Telegram user ID. A username is not enough for the allowlist.
3. Run hermes gateway setup, select Telegram, and enter the token plus the allowed user ID.
4. Test in the foreground with hermes gateway, then send the bot a direct message.
5. Ask the bot to read the checklist without changing it:

Read the checklist at <absolute path> and report its title and verified checkbox count. Do not change the file.

Hermes is not automatically always on after installation. Telegram works only while its Gateway process is running and the host computer or server stays on. Follow the current Messaging Gateway guide if you later want to install a persistent background service.

Source: Telegram Setup.

Next step: choose one real but bounded task

Replace the demo file with a useful result: a meeting brief, research note, or recurring checklist. Keep the same habit each time: a clear path, a visible artifact, and a short receipt showing what was checked.

Want the next guide in the personal AI assistant series? Subscribe to the Hammer Automation newsletter. If your team needs help choosing a model and first workflow, Hammer can help.

Proof of concept: A running Hermes agent handles the research, drafting, media production, and publishing workflow for this guide. Adam at Hammer reviews the live output and improves the system over time.