Buenos días, mi gente. Luis Randomness here — coming to you from sunny South Florida, cafecito in hand, with a question I hear from business owners every week: "Luis, I love what AI can do, but I don't want another subscription tab. I want a helper. Mine. One that knows my business."
Good news: that helper is buildable today, without a data center or a computer science degree. The tool is Hermes Agent, an open-source AI agent framework from Nous Research. This Hermes Agent tutorial walks the whole build — installation, model configuration, custom instructions, persistent memory, and the permission safeguards that keep you in charge. By the end, you'll have an assistant that can run commands, work with your files, remember how you like things done, and even answer you from your phone.
Let's build it.
What Hermes Agent actually is (and isn't)
Hermes is not a chatbot in a browser tab. It's an agent runtime on your computer or a server you control: you connect it to a large language model — the "brain" — and Hermes gives that brain hands: a terminal, file tools, web search, reusable skills, and messaging gateways, all governed by permissions you set. And since Hermes is a young, fast-moving project, this tutorial follows its official documentation (linked in the references) as the source of truth — if a random blog shows you a command that isn't in the docs, trust the docs.
Step 1: Install Hermes Agent
First, the quickstart's short prerequisites: a supported system (Linux, macOS, or Windows), a model with at least 64,000 tokens of context — the working memory an agent needs for multi-step tasks, which most modern hosted models provide — and a way to pay for the brain: an API key, a supported provider subscription, or a Nous Portal account. No GPU farm, no Kubernetes; a laptop or small cloud server is plenty.
On macOS or Windows, the easiest route is the Hermes Desktop installer from the Hermes website, which installs the desktop app and command-line tool together. For a command-line-only install on Linux, macOS, or WSL2, the official quickstart gives a single shell-installer command served from the Hermes Agent site (hermes-agent.nousresearch.com); native Windows gets the equivalent PowerShell one-liner. (Exact commands are in the quickstart — flagged in the editor's notes to be pasted in verbatim at publish time.) When the installer finishes, reload your shell so the `hermes` command is available:
source ~/.bashrc # or: source ~/.zshrc
And run `hermes doctor` whenever something feels off — it's the built-in health check and step one of the official recovery toolkit.
Step 2: Connect a model with `hermes setup` and `hermes model`
This is the single most important step. Running `hermes setup` launches the wizard, which on a fresh install offers three modes:
- Quick Setup (Nous Portal) — an OAuth login with no API keys to manage. Per Nous Research's documentation, one Portal subscription covers 300+ models plus its Tool Gateway (web search, image generation, text-to-speech, cloud browser). The one-command version is `hermes setup --portal`.
- Full Setup — walk through every provider and option yourself, bringing your own API keys.
- Blank Slate — everything starts off except the bare minimum: a provider and model, file operations, and the terminal. Pick this for a tightly controlled agent where you enable only exactly what you need.
Already know your provider? Run `hermes model` for an interactive walk-through — Nous Portal, Anthropic, OpenAI Codex, OpenRouter, and many more, plus custom endpoints for self-hosted or OpenAI-compatible servers, and local options like Ollama or LM Studio if you want the brain on your own hardware.
Secrets live in `~/.hermes/.env`, all other settings in `~/.hermes/config.yaml`, and `hermes config set` routes each value to the right file automatically. Switch models anytime with `hermes model` — no rebuild, no lock-in.
Step 3: Say hello — your first chat
Start the agent:
hermes # classic command-line interface
hermes --tui # the newer terminal interface, recommended by the docs
You'll get a welcome banner showing your model and tools. The quickstart's rule of thumb is gold: if Hermes can't complete a normal chat, don't add more features yet. Ask something specific and verifiable — "Summarize this folder in five bullets and tell me what the main project file is" — and watch it use a tool, answer, and hold the conversation past one turn.
Inside the chat, typing `/` opens the slash-command menu (`/help`, `/tools`, `/model`, `/save` cover most days). And your conversation survives closing the terminal: `hermes --continue` (or `hermes -c`) resumes your most recent session, because sessions are stored locally in a database at `~/.hermes/state.db` — the foundation for the memory magic in Step 5.
Step 4: Give your helper a personality with custom instructions
A generic agent gives generic help. Hermes lets you shape who your helper is through instruction files:
- `~/.hermes/SOUL.md` — the agent's primary identity: personality, tone, communication style, and what to avoid. Hermes seeds a starter file if one doesn't exist and never overwrites yours. It's the first thing loaded into the system prompt at every session start, so one thoughtful edit here flavors every conversation afterward.
- `AGENTS.md` in a project folder — instructions for that project: conventions, commands, paths, workflows. Hermes loads it when working in that directory, so your coding project and your marketing folder can teach the same helper different manners.
My advice: write your SOUL.md like a first-day briefing for a brilliant new employee — how formal, how brief, and what it must never do without asking. At Lagoon of Randomness our helpers know the brands and the vibe because we wrote it down once, properly, instead of re-explaining it every morning.
Step 5: Turn on persistent memory
Here's where a chatbot becomes a helper. Hermes maintains two memory files in `~/.hermes/memories/`:
- `MEMORY.md` — the agent's own notes: environment facts, project conventions, tool quirks, things learned working with you.
- `USER.md` — the profile it builds of you: preferences, working style, expectations.
The agent writes to these files itself as you work together, and at each session start they're loaded into its context as a snapshot — so it greets you already knowing reports go out on Fridays and clients get summaries, not spreadsheets. You can review and edit what's remembered, and the documentation describes approval gating for memory saves, so the agent doesn't quietly file away things you'd rather it forgot. Start small — services, tone, recurring tasks — then let memory grow from real work. A helper that remembers is a helper that compounds.
Step 6: Set the permission safeguards (do not skip this)
An agent that can run commands is powerful, which is exactly why Hermes wraps risky actions in an approval system. Per the official security documentation (linked in the references), when the agent wants to run a potentially dangerous command, you get a prompt showing exactly what will execute — for example, a recursive delete — with four choices:
DANGEROUS COMMAND prompt — options:[o]nce | [s]ession | [a]lways | [d]eny
Your four choices: once (allow this single execution), session (allow this pattern until you close the session), always (add it to your permanent allowlist in `config.yaml` — review it anytime with `hermes config edit`), and deny (the default; the command is blocked).
You control strictness through `approvals.mode`: smart (the default — an auxiliary model assesses flagged commands, auto-approving only genuinely low-risk ones for that single run and escalating or denying the rest), manual (you approve every flagged command), or off (no checks — the docs warn this belongs only in trusted, sandboxed environments, and so do I).
Two more safeguards for day one: sandbox the terminal — `hermes config set terminal.backend docker` runs the agent's commands in a Docker container instead of on your machine (or use the `ssh` backend for a remote server) — and tune the toolbox with `hermes tools`, which configures which tools are enabled per platform, so your phone-based helper doesn't need your workstation's reach.
And here's the design decision I respect most: in unattended situations — scheduled runs, background tasks — flagged actions are refused rather than auto-approved, because nobody is present to say yes. Your helper would rather stop and ask than improvise with your business — the same philosophy behind the human-approval checkpoint in AI as Your Email Manager: automate the prep, keep a human on the send button.
Step 7: Put your helper to work
- Skills. Skills are reusable instruction documents (`SKILL.md` files) that teach Hermes a specific workflow — your weekly report, a client summary, your morning checklist. Browse and install them with `hermes skills browse`, `hermes skills search`, and `hermes skills install` (installs run a security scan first), or write your own into `~/.hermes/skills/`. Every installed skill becomes a slash command.
- Messaging gateway. Run `hermes gateway setup` to connect Telegram, Discord, Slack, WhatsApp, Signal, email, and more — your helper, reachable from the beach, the airport, or the I-95 traffic jam. (Dangerous commands requested over messaging still wait for your yes or no in the chat.)
- Real business workflows. Morning briefings, research summaries with sources, first drafts of follow-ups awaiting your approval. Pair this build with our guide to AI email management, and keep the mindset from AI Won't Take Your Job—But It Can Make Your Work Easier: the helper handles the repetitive, you handle the relationships.
Your helper, your rules
Building your own AI helper with Hermes Agent isn't about chasing hype — it's about ownership: your model choice, your memory files, your permission rules, on your machine. Nous Research built the engine; you build the employee handbook.
If you'd rather have a crew that's done this before design the workflows, safeguards, and personality with you, that's literally what we do at CTRL+R Studio. Let CTRL+R Studio help design your AI workflow.
Now go make Monday morning feel a little more like Friday. The Coquí believes in you. 🐸
References
- Nous Research, Hermes Agent Quickstart — the official installation and configuration guide, at hermes-agent.nousresearch.com (docs > getting-started > quickstart).
- Nous Research, Hermes Agent Security documentation — command approvals, allowlists, and safety model, at hermes-agent.nousresearch.com (docs > user-guide > security).
- Nous Research, Hermes Agent on GitHub — the open-source project repository (NousResearch/hermes-agent).
