Getting Started with Hermes Agent
This guide walks you through installing and running Hermes Agent for the first time. By the end, you will have a working AI agent connected to at least one messaging platform, ready to start learning from your interactions.
Choose Your Deployment Method
Hermes Agent supports five deployment paths, but for getting started, two are recommended. Docker is the fastest self-hosted option and works on any Linux, macOS, or Windows (with WSL2) system. FlyHermes is the managed cloud option if you prefer not to manage infrastructure.
For this guide, we use the Docker path. You need Docker installed on your system (Docker Desktop for macOS/Windows, or docker-ce for Linux). If you do not have Docker, install it from docker.com before proceeding. You also need an API key from at least one model provider. OpenAI, Anthropic, or DeepSeek all work. If you want to run entirely locally, install Ollama and pull the hermes3:8b model.
Install Hermes Agent
Pull the official Docker image by running: docker pull nousresearch/hermes-agent:latest. Create a directory for your Hermes configuration and data. This directory will hold your config.yaml file, the memory database, and the skill library. The agent creates the database and skill directory automatically on first run.
Create a minimal docker-compose.yml file that mounts your configuration directory and exposes the web dashboard port (default 3000). The official repository includes example compose files for common configurations. Copy the example that matches your setup (cloud API, local Ollama, or mixed) and adjust the paths to match your directory structure.
Configure Your Model Provider
Create a config.yaml file in your configuration directory. The minimum viable configuration requires only a model provider section. For cloud APIs, add your provider name and API key. For Ollama, specify the local endpoint URL (typically http://localhost:11434 or http://host.docker.internal:11434 when running in Docker).
The configuration file also supports model routing, where you assign different models to different task types. For getting started, a single model is sufficient. You can add routing later as you learn which tasks benefit from different models. The agent detects your model's capabilities (vision, streaming, tool calling) automatically.
Connect a Messaging Platform
The simplest starting point is the built-in web dashboard, which requires no external configuration. It is enabled by default on port 3000. For a more practical setup, connect Telegram (create a bot through BotFather, add the token to config.yaml), Discord (create an application at discord.com/developers, add the bot token), or any other supported platform.
Each platform has its own authentication method documented in the Hermes configuration guide. Most platforms require creating a bot or application through the platform's developer portal and pasting the resulting token or credentials into your config.yaml. The agent handles connection management, reconnection on failure, and message formatting for each platform automatically.
Start and Verify
Launch the agent with docker compose up (or docker-compose up for older Docker versions). The first startup takes a few seconds while the agent initializes its memory database and skill library. Watch the logs for confirmation that the model provider and messaging platforms connected successfully.
Send a test message through your connected platform (or the web dashboard at localhost:3000). Try something that exercises the tool system, like asking the agent to check the current weather or summarize a webpage. If the agent responds and successfully uses tools, your installation is complete.
From here, the agent will begin building memory about you and your preferences. After solving complex tasks, it will create skill documents automatically. Over days and weeks of use, you will notice the agent becoming faster and more accurate on tasks it has handled before. Review the memory and skills directories periodically to see what the agent has learned.
Common Setup Issues and Solutions
The most frequent setup issue is Docker networking when running Ollama alongside Hermes in containers. The agent container needs to reach the Ollama endpoint, which requires either using Docker's host networking mode or configuring the endpoint as http://host.docker.internal:11434 (on macOS and Windows) or the host's IP address (on Linux). The Hermes Docker documentation includes platform-specific networking examples.
The second most common issue is model context length misconfiguration. Hermes requires models with at least 64K context windows. If your model's context is configured too low, the agent will produce truncated or confused responses because it cannot fit memory, skills, tools, and the conversation into the available window. For Ollama, check the model's context length with ollama show and increase it if necessary using the num_ctx parameter.
API key formatting errors cause silent failures on some providers. Double-check that your API keys are correctly copied into the config.yaml file, with no leading or trailing whitespace and the correct prefix format for each provider. The agent logs (visible through docker logs or the web dashboard) will show authentication errors if the key is invalid.
First Week Best Practices
The first week with Hermes is the most important for long-term agent quality. During this period, the agent is building its initial memory of your preferences, work patterns, and communication style. Investing effort in clear, detailed interactions during the first week pays dividends for months afterward.
Start with tasks that you perform regularly and would benefit from automation or assistance. This gives the skill system the best material to work with, creating skills for workflows you actually need rather than one-off experiments. Provide feedback when the agent does something well or poorly. The memory system picks up on corrections and adjusts behavior in future interactions.
Review the skills directory after the first few days of use. You will see SKILL.md files appearing as the agent encounters and solves new types of tasks. Read through these skills to verify they capture the correct approach. If a skill contains a mistake or suboptimal approach, you can edit it directly as a markdown file, and the agent will use the corrected version going forward.
Configure your soul file thoughtfully rather than accepting the defaults. A well-crafted soul file that describes your communication preferences, work context, and behavioral boundaries produces noticeably better interactions from day one. The soul file is not a one-time setup but an evolving document that you refine as you learn what works best with your specific use case and model combination.
After your initial setup is complete and the agent is responding to messages, take time to explore each configuration option gradually. The agent works well with default settings, and premature optimization of model routing, memory parameters, or tool permissions can introduce complexity before you understand the baseline behavior. Let the agent run for a few days with minimal customization, observe its performance, and then adjust settings based on actual usage patterns rather than theoretical optimization.
Getting started with Hermes Agent takes under ten minutes with Docker. Pull the image, create a config.yaml with your model provider credentials, optionally connect a messaging platform, and start the container.