How to Set Up Hermes Agent for SEO Optimization: Install, Tools, and Skills Step by Step
Hermes Agent is the open-source, MIT-licensed AI agent from Nous Research that runs in your terminal, remembers past work, and writes its own skills. This guide takes you from a blank machine to a working SEO agent: what to install, which model and search keys you need, the safety settings to change first, and a first audit prompt to test it.
What do you need before installing Hermes Agent?
You need five things; the installer handles the rest. 1. A supported machine: Linux, macOS on Apple Silicon, Windows (WSL2 or native PowerShell), or Android through Termux. Intel Macs are not supported, per the Hermes installation docs. 2. Git. On Linux you also need curl and xz-utils. 3. A model with at least 64,000 tokens of context, plus an account to reach it: Nous Portal, OpenRouter, Anthropic, and OpenAI all work. The docs set this floor because smaller windows cannot hold enough working memory for multi-step tool calls. 4. A web search option. A fresh install works on a keyless free-tier rotation, but for SEO research you want your own key (Firecrawl, Tavily, Exa, or Brave). The table further down compares them. 5. About 45 minutes, and access to the Google Search Console property you plan to work on (used in guide two). You do not install Python, Node.js, ripgrep, or ffmpeg yourself. The installer sets up all four.
How do you install and configure Hermes Agent for SEO?
Read the install script, then run it
Open https://hermes-agent.nousresearch.com/install.sh in a browser and skim it before piping it into bash. It is the official script, but reading what you run is a habit worth keeping for software that can execute commands on your machine. Then run the one-line installer for your platform. It clones the repo, creates a virtual environment, installs Python 3.11, Node.js, ripgrep, and ffmpeg, and puts the hermes command on your PATH.
# Linux, macOS (Apple Silicon), WSL2, Termux curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash # Windows (PowerShell) iex (irm https://hermes-agent.nousresearch.com/install.ps1)
Reload your shell and run hermes doctor
Reload your shell so the hermes command is found, then run hermes doctor before anything else. If you see "hermes: command not found", the reload is what is missing. hermes doctor checks your config and dependencies; hermes doctor --fix repairs what it can. Clear every problem it reports now. A half-broken install tends to fail later, mid-task, when the agent reaches for a tool that never loaded.
source ~/.bashrc # or: source ~/.zshrc on macOS hermes doctor hermes doctor --fix # only if doctor reports problems
Connect a model with hermes model
Run hermes model to open the provider wizard, sign in or paste an API key, and choose a default model with at least 64,000 tokens of context. For SEO audits, context is the limit you hit first: a fetched page, its HTML head, a competitor page, and your instructions can fill a small window before the agent writes a word. If you pay for Nous Portal, hermes setup --portal covers the model plus web search, browser, image generation, and TTS with one OAuth sign-in. Inside a chat, /model only switches between models you have already configured. Adding a provider always goes through hermes model.
hermes model # Nous Portal subscribers only: model + tool gateway in one step hermes setup --portal
Pin a web search backend the agent can rely on
Add one search API key to ~/.hermes/.env, then pin that backend in config so Hermes does not quietly switch providers. With no keys, Hermes rotates across the public free tiers of Exa, Parallel, Firecrawl, and Keenable. That is fine for a first try and a poor fit for SEO, where you want the same backend on every run so results stay comparable. Firecrawl is the default and handles both search and page extraction. If several keys are set and nothing is pinned, Hermes picks the first it finds in this order: Tavily, Perplexity, Exa, Parallel, Firecrawl, SearXNG, Brave, DDGS. Pinning search_backend and extract_backend, and turning off the keyless fallback, removes the guesswork.
# add to ~/.hermes/.env FIRECRAWL_API_KEY=fc-your-key-here # then pin the backend hermes config set web.search_backend firecrawl hermes config set web.extract_backend firecrawl hermes config set web.keyless_fallback false
Set approvals to manual and lock your secrets file
Switch command approvals to manual and restrict your .env file before the agent touches a real site. The default mode, smart, uses a second model to judge risk and auto-approves commands it rates low-risk. SEO work rarely needs the agent to run anything destructive, so being asked every time costs little and catches the one time it decides to "tidy up" a folder. Hermes also keeps a hard blocklist (rm -rf /, fork bombs) that no setting can override. Keep API keys only in ~/.hermes/.env with chmod 600. If you later run Hermes as a Telegram or Slack bot, the gateway denies every user until you configure an allowlist; leave that default alone until you know who needs access.
hermes config set approvals.mode manual chmod 600 ~/.hermes/.env
Write an AGENTS.md with the site facts the agent must not guess
Create one working folder per site, for example ~/seo/example-com, and put an AGENTS.md in it listing the facts the agent must never guess. Hermes loads AGENTS.md from the folder you start it in and up the git root chain, so launching hermes inside that folder gives every session the context. Include the domain and locale structure, the CMS, sections that are off-limits, banned words, and where product facts live. Keep it tight: ten specific rules beat a page of vague ones, and context files in subdirectories are capped at 8,000 characters. One gotcha: Hermes loads only one project context type per session, first match wins, and AGENTS.md outranks CLAUDE.md and .cursorrules. Tone that should apply everywhere belongs in ~/.hermes/SOUL.md instead.
Run a first audit on a page you know well
Start hermes inside your site folder and give it a narrow, checkable task: audit one URL you already know. Knowing the page is the point. Within a minute you can tell whether the agent actually fetched it (it quotes your real title tag and H1) or reconstructed a plausible page from training data (it describes headings you do not have). Watch the tool calls as it works. If no web_extract or browser call happens before it starts listing issues, the audit is fiction. Stop it and recheck your search backend from step 4.
Audit this single page for on-page SEO: https://example.com/your-page 1. Fetch the live page first. Quote the exact <title>, meta description, canonical URL, H1, and every H2. 2. List an issue only if you can point to the exact element or text that causes it. 3. For each issue give: element, current value, why it matters, a specific fix. 4. Label anything you could not verify from the fetched page as UNVERIFIED. 5. Do not estimate traffic, rankings, or search volume. You have no data source for that yet. Save the result to ./audits/<page-slug>-<YYYY-MM-DD>.md
What should your AGENTS.md and config look like?
# Site: example.com ## Facts (never guess these) - Locales: /en and /id, every URL is locale-prefixed - CMS: Next.js, content lives in the repo - Primary market: Indonesia - Source of truth for product facts: https://example.com/pricing ## Rules - Never edit files outside ./audits and ./briefs - Never publish, push, or submit anything to Search Console - Every number needs a URL or a named data source - Mark anything you could not verify as UNVERIFIED - Banned words in drafts: delve, leverage, seamless, robust, game-changer, unlock ## Output - Audits: ./audits/<slug>-<YYYY-MM-DD>.md - Briefs: ./briefs/<keyword>-<YYYY-MM-DD>.md
Specific beats long. The "never submit anything to Search Console" rule starts to matter once you connect it in guide two.
approvals: mode: manual web: search_backend: firecrawl extract_backend: firecrawl keyless_fallback: false
Open the file with hermes config edit, or set each key with hermes config set. Run hermes config path to confirm which file you are editing.
Which web search backend should an SEO agent use?
| Backend | Search / extract | Free tier (Hermes docs, Sep 2026) | Fit for SEO work |
|---|---|---|---|
| Firecrawl | Both (Hermes default) | 500 credits/month | All-rounder: full page fetches for audits |
| Tavily | Both | Keyless option | Research queries; supports crawling |
| Exa | Both | 1,000/month | Search and extract, no crawling |
| Brave Search | Search only | 2,000 queries/month | Pair with Firecrawl for extraction |
| SearXNG | Search only | Self-hosted, no API bill | Private, but you maintain the server |
| DDGS | Search only | Free, no key | Testing; pair with an extract backend |
Setup details that save time later
Give SEO its own profile if Hermes does other work
hermes profile create seo makes an isolated Hermes instance with its own settings, memory, and skills. Switch with hermes profile use seo, or pass -p seo on a single command. Run hermes config path afterwards so you know which config file you are editing. After a few weeks the payoff is a memory full of your sites and past findings, not mixed with unrelated tasks.
Confirm which context file actually loaded
Hermes loads one project context type per session in this order: .hermes.md, AGENTS.override.md, AGENTS.md, CLAUDE.md, .cursorrules. If your site repo already has a CLAUDE.md for another tool and you add AGENTS.md, the CLAUDE.md is ignored. Put your SEO rules in the file that wins.
Update with a backup
hermes update --check shows what would change; hermes update --backup snapshots your Hermes home folder before pulling. Skills and memory get more valuable the longer you use them, so the backup flag is cheap insurance.
Share hermes dump, not your config, when asking for help
hermes dump exports a redacted summary of your setup. That is what belongs in a GitHub issue or a team chat, rather than a config file that may hold credentials.
What this setup does not do yet
At this stage the agent has no ranking, traffic, or search volume data. It can read pages and search the web, nothing more, so any traffic or keyword volume figure it gives you is invented until you connect a data source in guide two. The steps were checked against the Hermes documentation on 15 September 2026, not pinned to a release number, and Hermes changes quickly: flags and config keys may move. The macOS installer supports Apple Silicon only. And a working install is not a working process. The agent will still produce confident, wrong output, which guide three teaches you to catch.
Frequently asked questions about Hermes Agent for SEO
Next: connect Search Console, DataForSEO, and SEO skills
Your agent can read pages but has no data yet. Guide two connects Google Search Console and DataForSEO through MCP, writes two SEO skills, and schedules a weekly report.
Read guide 2: Search Console, DataForSEO, and skillsKey takeaways
A working Hermes Agent SEO setup takes seven steps: read and run the installer, clear everything hermes doctor reports, connect a model with 64K+ context, pin one web search backend, set approvals to manual and lock your .env, write an AGENTS.md with site facts, and test on a page you know. That last test tells you the most. If the agent quotes your real title tag, the tools work. If it describes a page you don't recognize, nothing built on top will be trustworthy either.