2. Quickstart

This chapter takes you from nothing to a working agent in about ten minutes. You will install the CLI, start a local gateway, create an agent, send a message, and learn the three or four commands you will use every day.

2.1 Prerequisites

You need:

  • Node.js 20 or newer — check with node --version.
  • A PostgreSQL database — local Postgres, Docker Postgres, or a managed Postgres URL.
  • At least one model provider API key — Anthropic, OpenAI, or OpenRouter.

If you do not have Postgres handy, the docker-compose.yml at the root of the repo brings one up:

docker compose up -d postgres

2.2 Install the CLI

npm install -g openhermit

This installs the hermit command. Confirm it works:

hermit --version

2.3 Run the Setup Wizard

The fastest path is the interactive wizard. It walks through the database URL, the model provider, and the first agent in one pass.

hermit setup

When the wizard asks for things:

  • Postgres URL — for example postgres://postgres:postgres@localhost:5432/openhermit.
  • Provider — anthropic, openrouter, or openai.
  • API key — paste the key you got from your provider.
  • First agent ID — pick something short, like main.

The wizard creates the gateway config, runs database migrations, and starts the gateway in the background.

2.4 Verify the Setup

hermit doctor

doctor checks that the gateway is up, the database is reachable, your API key works, and your agent is registered. If it complains, the error tells you which piece is wrong.

hermit status

status gives you a one-screen overview: which agents exist, whether each is enabled, and which channels are connected.

2.5 Send Your First Message

Two ways.

From the terminal — open an interactive chat:

hermit chat --agent main

You will see a prompt. Type a message and press Enter. The agent streams its reply.

From the web UI — start the web server:

hermit web start

It tells you a URL (default http://localhost:4310). Open it in a browser, pick your agent, and chat. The gateway itself listens on http://localhost:4000.

Either way, the conversation is stored as a session and persists across restarts.

2.6 The Five Commands You Will Use Most

These are the commands worth learning today:

CommandWhat it does
hermit statusOne-screen overview of agents, channels, gateway state.
hermit chat --agent <id>Open an interactive chat with an agent.
hermit logs -fTail the gateway log; useful when something feels stuck.
hermit config show --agent <id>Print the current configuration for an agent.
hermit agents listList all agents in this instance.

Full command reference: Chapter 19 · CLI Cheatsheet.

2.7 What Now

You have a working agent. Some natural next steps: