Hermes Agent

Hermes Agent is an agent running in terminals that can read/write files, execute commands, and invoke tools after user authorization.

This tutorial explains how to use Hermes Agent's built-in Custom Endpoint to connect to AGTCloud's Chat Completions API and verify basic conversations without additional configuration tools. File operations, web search, MCP, Skills, and other extensions are outside the scope of this tutorial's verification.

Preparation

Before you start, please confirm that you have:

Prepare the operating system and terminal environment supported by Hermes Agent;
Register and log in to AGTCloud;
Create the AGTCloud API Key on the API Keys page;
Copy the model ID from the Model Marketplace which is available to the current API Key and supports Chat Completions;
Prepare a test directory that does not contain sensitive code and production credentials.

Install Hermes Agent

Choose the official installation method for your environment. The initial macOS release supports Apple Silicon only. Intel Macs, Homebrew, and PyPI installations are not currently supported through official channels.

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

After installation, reopen the terminal and check the version and operating environment:

hermes version
hermes doctor

hermes doctor checks installation, configuration, and common runtime issues. If the terminal cannot find hermes, reopen it and confirm that the installation directory is in PATH. For other platform limitations, see the official Hermes Agent platform support notes.

Configure AGTCloud

Hermes Agent provides a model service provider configuration wizard. Please run the following command in a regular terminal and do not execute it in an open Hermes conversation:

hermes model

Select Custom Endpoint

Select Custom endpoint. The full name may appear in different versions Custom endpoint (self-hosted / VLLM / etc.) in the Provider list.

Fill in the AGTCloud connection information

Fill in the following order according to the current version wizard:

Hermes Agent field	Value
`Provider Name` (if shown)	`AGTCloud`
`API Base URL`	`https://api.agtcloud.cn/v1`
`API Key`	`your-api-key`
`API / Wire Mode`	`Chat Completions` or `chat_completions`
`Model`	`MODEL_ID`
`Context Length`	For the initial setup, leave this blank so the client can try to detect it automatically

Replace your-api-key with the AGTCloud API Key and MODEL_ID with a model ID available to that API Key.

Save the configuration

Review the wizard summary, then save the configuration. Hermes Agent normally writes general settings to ~/.hermes/config.yaml and stores the API Key and other sensitive values in ~/.hermes/.env.

The base URL must include /v1

Use https://api.agtcloud.cn/v1 exactly as shown. Do not enter only the API Origin, append another /v1, or enter the full /v1/chat/completions endpoint.

Prioritize using the official configuration wizard

The configuration fields of Hermes Agent may evolve with each version. Using hermes model allows the current version to write the correct Provider and transport mode by itself, without manually editing YAML or writing the real API Key into shared configuration examples.

Check the configuration

After completing the wizard, you can use the following command to check the current settings:

hermes config
hermes config get model
hermes config check

hermes config opens or displays the current configuration;
hermes config get model shows the current model settings;
hermes config check validates the configuration format and required fields.

Do not copy or share the full API Key when checking output. If the configuration still points to another Provider, restart hermes model and complete the Custom Endpoint setup.

Start and verify the connection

Enter the security testing directory

cd /path/to/safe/test-project

The first connection should not be made in directories containing production credentials, customer information, or undisclosed source code.

Launch Hermes Agent

hermes

You can also use hermes chat to start an interactive session.

Complete basic dialogue verification

Send in the input box:

Please only reply: AGTCloud Connection successful. Do not use any tools.

If you receive a reply normally, it means the base URL, API Key, model, and basic Chat Completions connection have been established. This step will generate normal API usage.

Optional verification tool call

If the selected model supports tool calls, you can send them in the test directory containing the README.md:

Please read only the README.md and summarize the project's purpose in three points. Do not modify the file or execute other commands.

Keep manual approval enabled. Review each action Hermes Agent proposes before allowing it.

Do not disable operation approval for the first use

Do not use --yolo or disable approval for potentially dangerous operations. Hermes Agent can execute commands and access files, so review each tool request during the initial validation.

Switch models

When you need to add a new model, modify an Endpoint, or change an API Key, exit the current session and run:

hermes model

In an active session, use /model to switch between configured Providers and models. /model does not create a new Custom Endpoint. If the target model has not been configured, exit the session and run hermes model in the terminal first.

MODEL_ID is just a placeholder. Always use the full model ID visible in the current API Key in Model Marketplace, and do not rely on fixed recommended models that may change with versions.

Frequently Asked Questions

Issue	What to check	Resolution
Cannot find the `hermes` command	Installation and `PATH`	Reopen the terminal and run `hermes version`; if it is still unavailable, rerun the official installer for your operating system
`hermes doctor` reports a problem	Python, system tools, and installation directory	Follow the diagnostic output to repair the environment, and avoid mixing multiple Hermes Agent installation methods
Returns `401`	API Key value and token status	Copy a valid API Key again and make sure the field contains no extra spaces
Returns `403`	Token permissions, model permissions, and account status	Check the API Key status and the models available to the current account in the console
Returns `404`	Base URL, duplicated `/v1`, and model ID	Use `https://api.agtcloud.cn/v1`, do not enter a full endpoint, and copy the complete model ID again
The model is unavailable	Models visible to the current API Key and protocol support	Select a model available to the current API Key that supports Chat Completions
Hermes still uses another Provider	Current selection in `hermes model` and whether it was saved	Run the wizard again, select Custom Endpoint, save the configuration, and validate it with `hermes config check`
Conversation works, but a tool call fails	Model tool-calling capability and response format	Switch to a model that supports tool calls, disable complex tools, and validate a single read-only operation first
Context-length detection fails	Model metadata and manually entered values	Run `hermes model` again. Enter a context length manually only when the model's actual limit is known
Optional tools lack credentials	Separate service configuration for auxiliary tools	These features may require additional services and credentials; they are not configured by the API Key used for the main AGTCloud chat model

If you cannot identify the cause of an issue, run hermes doctor and hermes config check, then record the request time, API Base URL, model ID, HTTP status, and sanitized error messages. Review Errors and troubleshooting, and never submit the full API Key.

Safety advice

Do not write API keys into project files, Git repositories, command logs, screenshots, logs, or shared configurations;
The first use should be conducted in the security test directory, with each file, command, and network access request checked item by item;
Do not disable hazardous operation confirmation through --yolo or configuration items;
When handling untrusted code, you can use isolated environments like Docker to reduce risk, but you still need to check mount directories and credentials;
If an API Key is suspected of leaking, immediately disable or remove it in the console, then create a new Key.