Lesson 2 of 6
Install Hermes and have your first conversation
One install command, connect your ChatGPT subscription via Codex OAuth, and have your first conversation — no API billing required.
The install is one command. What comes after — provider selection, API key setup, first run — is where beginners usually get stuck. This lesson collapses all of it into a single guided sequence with no dead ends.
Install
Open Terminal and run:
curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash
The script detects your OS (macOS, Linux, WSL2) and installs Hermes to ~/.hermes/. When it finishes, reload your shell:
source ~/.zshrc
# or: source ~/.bashrc
Confirm the install worked:
hermes version
Choose a provider
Hermes needs a language model to think with. Run the interactive picker:
hermes model
This course uses GPT-5.5 via OpenAI Codex — connected through your existing ChatGPT subscription using OAuth, not API billing. If you're already paying $20/month for ChatGPT Plus (or $100/$200 for Pro), this gives you GPT-5.5 in Hermes at no additional cost. Select Codex as your provider during setup and authenticate via browser — no API key required.
For heavier autonomous work — long cron jobs, overnight research tasks, multi-turn sessions — you can pair Codex with a direct OpenAI API key as a fallback. Hermes supports this with hermes fallback: your Codex subscription handles interactive sessions, the API key handles scheduled background tasks that run while you're away.
hermes model # set Codex (OAuth) as primary
hermes fallback # optionally add OpenAI API key as fallback
Cost comparison: Direct OpenAI API billing for GPT-5.5 charges per token — heavy use adds up fast. Codex OAuth routes through your ChatGPT subscription, so interactive sessions cost nothing extra. The combination of Codex (primary) + API key (fallback) gives you the best of both: subscription value for daily use, API access for autonomy.
Other good options: OpenRouter gives you access to a wide range of models under one API key — useful if you want to experiment or don't have a ChatGPT subscription. Nous Portal is the simplest entry point with no key at all, just sign in. All providers work identically for the rest of this course.
Add a fallback API key (optional but recommended)
If you set up a direct API key as fallback, store it the right way — never paste it into chat:
hermes config set OPENAI_API_KEY sk-...
hermes config set automatically routes API keys to ~/.hermes/.env (never committed to git, never shown to the model) and everything else to ~/.hermes/config.yaml.
Never paste an API key directly into a Hermes chat. Keys in chat end up in session logs at ~/.hermes/state.db. Always use hermes config set.
Run the setup wizard
The setup wizard walks through every configuration section in one go:
hermes setup
Sections it covers: model, text-to-speech, terminal backend, gateway, tools, and agent behavior. For now, accept the defaults on everything except model (which you already set). You can come back to any section with hermes config edit.
Start your first chat
hermes
Or, for the terminal UI with mouse support and panels:
hermes --tui
Try this prompt to confirm tools are working:
What can you do? List your most useful built-in tools in one short paragraph, then show me the top 3 directories by size in my home folder.
If Hermes lists tools and then runs a disk usage command, everything is working. The second part of the prompt confirms the terminal tool is active — that's the capability that separates Hermes from a browser chatbot.
Verify setup is clean
hermes status
All sections should show green. If anything is red, run hermes doctor for a diagnostic, or hermes dump for a copy-pasteable support summary you can drop into the Nous Research Discord.
Keeping your laptop awake
Hermes needs your machine to stay on and connected to run sessions and cron jobs. On macOS, the system will sleep after inactivity by default and kill the process.
Fix this with Amphetamine — a free Mac App Store utility that keeps your laptop awake on a schedule or indefinitely. Enable it before any long-running Hermes task.
Strongly consider a VPS for this. Running Hermes on your laptop means it's offline when your laptop is asleep, closed, or out of battery. A $5/month VPS (Hetzner CX22 or Hostinger KVM2) keeps Hermes always-on with no battery anxiety. Hostinger's marketplace has a Hermes one-click install — the whole setup takes about 10 minutes. The Discord lesson (Lesson 4) is where this payoff becomes obvious: Hermes on a server replies to your phone while your laptop is in a bag. If you want that, set up the VPS before Lesson 4.
One-shot mode
Not every interaction needs a full chat session. For quick tasks:
hermes -z "what's my current git branch and are there any uncommitted changes?"
The -z flag runs a single prompt and exits. Useful in scripts, aliases, and anywhere you just need a quick answer.
The next lesson gives Hermes a personality and makes it context-aware of your projects.