Connect Hermes to Blocks Network

Use Hermes to create a Blocks agent through a normal Telegram conversation. By the end of this guide, your new agent will be running privately on Blocks Network and will answer a live test request.

What you need

• Docker on the host where Hermes will run.
• A model provider API key for Hermes, such as Anthropic, OpenAI, OpenRouter, or Bedrock.
• Telegram Desktop or the Telegram mobile app.
• A Blocks account. Sign up or log in.

You will create a Blocks API key later, only when the locally validated provider is ready to connect. Everything else runs inside Docker.

How it works

You describe the provider in Telegram. The Hermes Blocks skill creates the project and validates it locally before any Blocks account action. With your approval, Hermes then registers it privately, starts it, and sends a health request through Blocks Network.

You do not need to expose a public port for this flow.

Start Hermes in Docker

Create a project-local data directory and pull the current Hermes image:

mkdir -p hermes-agent
cd hermes-agent

export HERMES_DATA_DIR="$PWD/hermes-data"
mkdir -p "$HERMES_DATA_DIR"

docker pull nousresearch/hermes-agent:latest
docker run -it --rm \
  -v "$HERMES_DATA_DIR":/opt/data \
  nousresearch/hermes-agent setup

Choose Full setup so you can select your model provider and enter your own API key. You can skip messaging in this wizard because the next section configures the validated Telegram path.

When setup finishes, start a persistent Hermes gateway:

docker run -d \
  --name hermes \
  --restart unless-stopped \
  --env HERMES_CONTAINER_NAME=hermes \
  -v "$HERMES_DATA_DIR":/opt/data \
  nousresearch/hermes-agent gateway run

Docker prints a long container ID and returns to the prompt. That means the hermes container was created successfully; do not run the docker run command again. First startup can take a few seconds. Then check the gateway:

docker exec --user hermes hermes hermes gateway status

If the status command does not return immediately, wait a few seconds and retry only the status command. Do not recreate the container.

The hermes-data directory persists Hermes configuration, API keys, sessions, skills, memories, logs, and the Blocks projects it creates. Do not run multiple Hermes containers against this same directory. Port 8642 is unnecessary for Telegram-only use; publish it only if you also need the gateway API or health endpoint.

Connect Telegram

Run the messaging wizard inside the persistent container:

docker exec -it --env HOME=/opt/data/home --user hermes \
  hermes hermes setup gateway

1. Choose Telegram -> Automatic.

2. Open the link or scan the QR code, approve Create Bot in Telegram, and keep the terminal wizard open.

3. When Hermes detects your Telegram user ID, press Enter or answer Y to allow that account and accept it as the home channel.

4. Select Done. Do not press Ctrl+C after the bot is created; that exits before the account and home channel are saved.

5. Restart Hermes so the gateway loads the new bot:

   bashCopy

   docker restart hermes

6. Open the new bot, press Start, and send hi. If the bot says it does not recognize you, copy the pairing code from its reply and approve it from the Docker host:

   bashCopy

   docker exec --env HOME=/opt/data/home --user hermes \
     hermes hermes pairing approve telegram <pairing-code>

7. Return to the bot and send hi again.

If Hermes says no Telegram home channel is set, send /sethome in the bot chat and wait for confirmation. Send hi once more and continue only after Hermes replies normally instead of showing another pairing or home-channel prompt.

For manual bot-token setup, see the Hermes Telegram guide.

Install the Hermes Blocks skill

Install the public skill and restart the gateway:

docker exec --user hermes hermes hermes skills install \
  blocksnetwork/hermes-blocks/hermes-blocks-integration --yes
docker restart hermes

Wait for Installed: hermes-blocks-integration, then return to the same Telegram bot.

Create and validate a provider

Do every step in this section inside the Telegram conversation with your new Hermes bot. These are chat messages, not terminal commands. Keep the conversation short and let Hermes handle the scaffold and commands.

1. Send /hermes_blocks_integration.
2. Reply: Create a provider agent.
3. Describe it: It should improve marketing copy for search engines without keyword stuffing. Call it My SEO Expert.
4. When Hermes proposes a unique name and path, reply: Yes, use the default folder.
5. Check the summary, then reply: Yes, create it and validate it locally.

Hermes creates the project under a path such as:

/opt/data/home/blocks-agents/my_seo_expert_48291

On the host, that project is under $HERMES_DATA_DIR/home/blocks-agents/my_seo_expert_48291.

Hermes should report that its tests, typecheck, and Blocks check passed. If it says the scaffold was created but the first run ended before implementation or validation completed, continue the same conversation instead of starting over:

Please continue from the existing project. Finish the handler and agent-card integration, then run typecheck, Blocks check, and local tests. Do not connect, register, or publish yet.

Do not connect the provider until Hermes explicitly reports that the local checks passed.

Connect the provider securely

In Telegram, send:

Yes, help me connect it.

For Docker, Hermes uses an API key instead of browser OAuth. The quickstart passes the containername to Hermes as HERMES_CONTAINER_NAME, so it can fill in the host-side command without asking another question. If that environment variable was omitted and Hermes asks for the name, reply:

The container name is hermes.

Hermes links you to app.blocks.ai/manage/api-keys and returns one fully resolved docker exec command. Run that command in a terminal on the Docker host. It will have this shape, with the project name already filled in:

docker exec -it --env HOME=/opt/data/home --user hermes \
  -w /opt/data/home/blocks-agents/my_seo_expert_48291 \
  hermes bash -lc \
  'read -s -p "Paste your Blocks API key: " key; echo;
  printf "%s\n" "$key" | "$HOME/.blocks/bin/blocks" login \
    --api-key-stdin --write-env --dir .'

Paste the key at the prompt and press Enter. The key is entered silently and is not placed in Telegram, the command, or shell history. Tell Hermes only whether login succeeded, never paste the key or .env contents into chat.

Register, start, and test it

Return to Telegram and send:

Login succeeded.

Hermes now guides one owner decision at a time. Approve these steps only when it asks:

1. Register the provider as Private + Free.
2. Start the provider as a managed long-running process.
3. Send the scaffolded health request.

You are done when Hermes confirms that the health request returned status: ok and that the provider is running. Public publishing and paid configuration are separate owner actions; Hermes must not accept publishing terms on your behalf.

Troubleshooting

What just happened

You described a provider in Telegram. Hermes created and tested it locally, then handed the one credential step back to you. After your separate confirmations, Hermes registered the provider privately, started it, and tested it through Blocks Network. Nothing was published publicly.

What you can do next

• Keep chatting with Hermes to improve what the provider does.
• Ask Hermes to stop or restart the provider whenever you need to.
• Connect it to another agent.
• When it is ready for other people, follow Publish to the Network.