Learn Hermes AI Agent - Installation & Basic Setup

#Introduction

In episode 2 you learned about Hermes's internal architecture: controller, kernel, tools, memory, and environment, plus the four-phase lifecycle. Now it is time to bring all of those concepts down to real practice — installing Hermes, creating a project, and running your first agent.

Here is the roadmap for this episode: we will lay out a Hermes Agent project, install dependencies, configure the runtime and model providers, run your first local agent, and close with quick troubleshooting for the problems that most often appear at the start.

#Laying Out a Hermes Agent Project

The first step is to scaffold the project. From episode 0, you already know how — now let's run it and dissect the structure:

Creating a Hermes Agent project

npm create hermes-agent@latest{:npm} my-agent
cd my-agent

When it finishes, the project structure will look like this:

Hermes Agent project structure

my-agent/
  profiles/          <- agent profile definitions
  tools/             <- custom actions and tools
  .env.local         <- credentials (not committed)
  hermes.config.yaml <- runtime configuration
  package.json

Get into the habit of writing the whole project as code under git version control from the start — initializing the repository now will pay off when we discuss configuration management in episode 10.

#Installing Dependencies

The scaffold already includes a package.json. Install its dependencies with your package manager of choice:

Installing dependencies with npm

npm install

Alternative with bun

bun install

npm ls @hermes/sdk

Make sure the @hermes/sdk shows up in the list. If it does, your project is ready to configure. Note: LLM provider credentials must also be available as environment variables as prepared in episode 0 — copy .env.example to .env.local and fill in the values.

#Initial Configuration: Agent Runtime and Model Provider

The hermes.config.yaml file is the center of the runtime configuration. Start with a minimal configuration: a default model and provider.

hermes.config.yaml - initial configuration

model:
  default: gpt-4o
  provider: openai
 
runtime:
  max_iterations: 90
  session_store: sqlite
  home: ~/.hermes
 
terminal:
  backend: local

Let's break down the important parts:

Key	Meaning
`model.default`	The model used when there is no override
`model.provider`	The provider that serves that model
`runtime.max_iterations`	The tool-call loop limit per conversation
`runtime.home`	The Hermes data directory: config, memory, sessions
`terminal.backend`	Where tools execute: local, docker, ssh, or cloud

Credentials are not written in this file — the provider reads environment variables such as OPENAI_API_KEY automatically. This is the same pattern we use throughout the series: configuration may go into git, secrets do not.

To select or change the model interactively, the CLI provides a wizard:

Choosing a provider and model

hermes model

That command shows a list of providers and models. The choice you make is saved to the runtime configuration.

Warning

Never write API key values into hermes.config.yaml or into code. Always rely on the environment variables that the provider references, and store the actual values in a secret manager or an uncommitted dot-env file.

#Running Your First Local Agent

Time for the moment you have been waiting for: running the agent. Just launch the CLI:

Running your first agent

hermes

Hermes will start an interactive conversation session in the terminal. Try sending a simple question:

First conversation

> Halo, siapa kamu dan tool apa yang bisa kamu pakai?

The agent will respond, introduce itself, and mention the available tools. To see the full command history and session capabilities, type /help inside the session. If the agent has not responded yet, jump to the troubleshooting section below.

If you want to run a single question without an interactive session, use one-shot mode:

One-shot mode

hermes run "Rangkum tiga manfaat AI agent dalam satu kalimat"

This mode is useful for quick testing and will later be used in CI pipelines — we will cover that in episode 19.

#Quick Troubleshooting

The most common problems in the initial setup, and their solutions:

hermes: command not found: the CLI is not on your PATH. Rerun npm create hermes-agent@latest and make sure you follow the path instructions it prints, or install the CLI globally.
401 Unauthorized when calling the model: credentials are not set or are wrong. Check OPENAI_API_KEY or whichever provider key you use, then set it as an environment variable.
model not found: the model name is not recognized by the provider. Run hermes model and choose from the official list.
Timeout or slow responses: usually the network or the provider is busy. Try a lighter model for initial testing.
Overall setup checkup: run the automatic diagnostics with hermes doctor — this tool checks config, credentials, and provider connectivity all at once:

Diagnosing the environment

hermes doctor

If hermes doctor runs without errors, your environment is healthy enough to continue to the next episode.

#Conclusion

In episode 3 you completed the full setup cycle: laying out the project, installing dependencies, configuring the runtime and model providers, running your first local agent, and learning the troubleshooting for common problems. Your agent is now alive and can be spoken to.

Key takeaways:

Scaffolding a project starts with npm create hermes-agent@latest and then installing its dependencies.
Runtime configuration lives in hermes.config.yaml; secrets stay in environment variables.
runtime.max_iterations limits the tool-call loop so the agent does not spin endlessly.
hermes opens an interactive session; hermes run for one-shot; hermes model to pick a model.
hermes doctor is the first diagnostic tool before debugging more deeply.

In the next episode 4 we will cover creating agent profiles and capabilities — writing persona, goals, and default behavior; defining capabilities such as browsing, code execution, and database access; through to defining the toolset and permission limits. Get your agent ready, because we are going to shape its personality and authority!