Optional Pre-work Setup

Do this before the workshop if you can. It is not mandatory, but every minute you spend here turns into more custom build time during the session.

Plan on 45-75 minutes total if you are installing Hermes for the first time. If you already have a working model subscription or API key, you may finish faster.

The official Hermes docs are the source of truth: Hermes documentation. If this page and the docs ever disagree, trust the docs.

Safety First

• Do not paste API keys, bot tokens, passwords, or private credentials into prompts.
• Do not commit .env, .hermes/, bot tokens, API keys, or local machine state.
• Start with read-only access for real systems.
• Give Hermes the least privilege needed for the thing you are building.

1. Choose a Model Path (10-15 min)

Pick one path now so the workshop setup does not stall on provider decisions.

Recommended

OpenAI Codex through ChatGPT/Codex if you already have access. In hermes model, choose the OpenAI Codex provider and complete the login flow.

Good fallback

OpenRouter with a free-tier model is good enough for workshop setup and a first smoke test. Free-tier usage can be limited and may have privacy/training tradeoffs, so avoid sensitive data.

Other viable paths

These are also reasonable if you already have an account, subscription, or API key ready:

• Nous Portal.
• GitHub Copilot.
• Anthropic / Claude.
• Google Gemini.
• Qwen OAuth.
• xAI Grok OAuth.
• OpenAI API.

Advanced/local

Local models, LM Studio, OpenAI-compatible custom endpoints, and other advanced setups can work well, but they are easier to debug before the workshop than during it. Use this path if you are already comfortable troubleshooting local model servers.

Provider support changes. Use the Hermes provider/model docs and the interactive picker as the current source:

hermes model

2. Install Hermes (10-20 min)

Official install guide: Installation

Default Linux, macOS, and WSL2 install path:

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

Reload your shell if prompted, then confirm Hermes is available:

hermes --version

3. Configure Your Model (5-15 min)

Run the model picker:

hermes model

Choose the provider you prepared in step 1. If you do not have a paid subscription ready, use OpenRouter with a free-tier model so you can keep moving.

4. Smoke Test the CLI (5-10 min)

Start Hermes locally:

hermes --tui

Ask something simple, then inspect the available tools and skills:

hermes tools list --platform cli
hermes skills list

If those commands work, you are ready for the main workshop.

5. Optional: Docker Backend (10-20 min)

For the workshop, the local terminal backend is the lowest-friction path. If you want more isolation, set up the Docker backend ahead of time so Hermes commands run in a container instead of directly on your host.

Docs: Docker backend

This is optional. Do not burn workshop time debugging Docker unless you specifically want that isolation.

6. Optional: Telegram Gateway (10-20 min)

Telegram is a good live workshop gateway because setup is fast and the feedback loop feels real. If you want to prepare it early, create your bot token before the session, then run:

hermes gateway setup

Docs:

• Messaging overview
• Telegram setup

Keep the token private. Treat bot tokens like API keys.

Troubleshooting

• Run the built-in health check:

hermes doctor

• Re-run the model picker if authentication, provider selection, or model choice looks wrong:

hermes model

• Check the official docs first: Hermes documentation.
• Bring the exact error message, your operating system, and the command you ran to the workshop. Do not share private keys or tokens.

Ready Checklist

Required:

• [ ] Hermes installed.
• [ ] One provider/model configured.
• [ ] hermes --version works.
• [ ] hermes --tui can answer a simple prompt.

Helpful but optional:

• [ ] Docker backend tested if you want container isolation.
• [ ] Telegram bot token created and gateway tested if you want live messaging.
• [ ] hermes doctor output reviewed if anything feels off.