Hermes Agent

Install Hermes Agent

Run this command to install Hermes Agent. The script automatically installs dependencies like Python and Git.
```
curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash
```
Note
Windows does not support native installation. Install WSL2 first, then run the above command in WSL2.

After installation, reload the terminal environment.

source ~/.bashrc    # If using zsh, change to source ~/.zshrc

Verify the installation. A version number confirms success.
```
hermes --version
```

Configure Access Credentials

Run hermes config set to configure the Base URL and API Key for your chosen plan:

Token Plan (Personal Edition): A personal subscription that deducts personal Credits based on token consumption.
Token Plan (Team Edition): Seat-based subscription; token consumption deducts Credits.
Coding Plan: Fixed monthly subscription, metered by model invocation count.
Pay-as-you-go: Post-paid based on actual usage.

Note

The examples in this topic use the Anthropic-compatible protocol: the Base URL ends with /apps/anthropic and api_mode is set to anthropic_messages. Hermes Agent also supports the OpenAI-compatible protocol: replace the trailing /apps/anthropic in the Base URL with /compatible-mode/v1 and remove the api_mode setting. For example, the OpenAI-compatible Base URL for Pay-as-you-go (China North 2, Beijing) is https://dashscope.aliyuncs.com/compatible-mode/v1.

In addition to the command-line version, Hermes Agent also offers a desktop version (Hermes Desktop). You can download the installer from the Hermes website, or run hermes desktop after installing the command-line version. Hermes Desktop and the command-line version share the same ~/.hermes/config.yaml configuration file, so the access parameters are identical to those described here. When connecting through a Custom Endpoint in the desktop app, use the OpenAI-compatible Base URL described above.

Token Plan (Personal Edition)

Replace YOUR_API_KEY with your Token Plan (Personal Edition) API Key. Available models are listed in supported models.

hermes config set model.provider custom
hermes config set model.base_url https://token-plan.cn-beijing.maas.aliyuncs.com/apps/anthropic
hermes config set model.api_mode anthropic_messages
hermes config set model.api_key YOUR_API_KEY
hermes config set model.default qwen3.8-max-preview

These commands write to ~/.hermes/config.yaml. You can also edit the file directly:

config.yaml example

model:
  default: qwen3.8-max-preview
  provider: custom
  base_url: https://token-plan.cn-beijing.maas.aliyuncs.com/apps/anthropic
  api_mode: anthropic_messages
  api_key: YOUR_API_KEY

Important

qwen3.8-max-preview thinking mode:

thinking: Always enabled. Cannot be disabled.
temperature: Defaults to 0.6 in thinking mode. Values below 0.6 are automatically adjusted to 0.6.
reasoning_effort: Controls reasoning depth. Options: xhigh, high, low. Default: xhigh.

Token Plan (Team Edition)

Replace YOUR_API_KEY with your Token Plan (Team Edition) API Key. Available models are listed in supported models.

hermes config set model.provider custom
hermes config set model.base_url https://token-plan.cn-beijing.maas.aliyuncs.com/apps/anthropic
hermes config set model.api_mode anthropic_messages
hermes config set model.api_key YOUR_API_KEY
hermes config set model.default qwen3.8-max-preview

These commands write to ~/.hermes/config.yaml. You can also edit the file directly:

config.yaml example

model:
  default: qwen3.8-max-preview
  provider: custom
  base_url: https://token-plan.cn-beijing.maas.aliyuncs.com/apps/anthropic
  api_mode: anthropic_messages
  api_key: YOUR_API_KEY

Important

qwen3.8-max-preview thinking mode:

thinking: Always enabled. Cannot be disabled.
temperature: Defaults to 0.6 in thinking mode. Values below 0.6 are automatically adjusted to 0.6.
reasoning_effort: Controls reasoning depth. Options: xhigh, high, low. Default: xhigh.

Coding Plan

Replace YOUR_API_KEY with your Coding Plan API Key. Available models are listed in supported models.

hermes config set model.provider custom
hermes config set model.base_url https://coding.dashscope.aliyuncs.com/apps/anthropic
hermes config set model.api_mode anthropic_messages
hermes config set model.api_key YOUR_API_KEY
hermes config set model.default qwen3.7-plus

These commands write to ~/.hermes/config.yaml. You can also edit the file directly:

config.yaml example

model:
  default: qwen3.7-plus
  provider: custom
  base_url: https://coding.dashscope.aliyuncs.com/apps/anthropic
  api_mode: anthropic_messages
  api_key: YOUR_API_KEY

Pay-as-you-go

Replace YOUR_API_KEY with your Alibaba Cloud Model Studio API Key. Available models are listed in Anthropic compatible API. Set base_url for your region. The API Key must match the selected region:

China North 2 (Beijing): https://dashscope.aliyuncs.com/apps/anthropic
Singapore: https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/apps/anthropic. Replace WorkspaceId with your actual Get the Workspace ID

hermes config set model.provider alibaba
hermes config set model.base_url https://dashscope.aliyuncs.com/apps/anthropic
hermes config set model.api_mode anthropic_messages
hermes config set model.api_key YOUR_API_KEY
hermes config set model.default qwen3.7-max

These commands write to ~/.hermes/config.yaml. You can also edit the file directly:

config.yaml example

model:
  default: qwen3.7-max
  provider: alibaba
  base_url: https://dashscope.aliyuncs.com/apps/anthropic
  api_mode: anthropic_messages
  api_key: YOUR_API_KEY

Verify Configuration

Send a test message to verify your configuration:

hermes chat -q "Hello"

A successful response confirms the configuration works. To switch models, use the -m parameter:

hermes chat -m qwen3.7-max

FAQ

Error Codes

For configuration errors, check the FAQ for your billing plan:

Pay-as-you-go: Error Code Troubleshooting
Coding Plan: Coding Plan FAQ
Token Plan (Personal Edition): Token Plan (Personal Edition) FAQ
Token Plan (Team Edition): Token Plan (Team Edition) FAQ