Hermes

Hermes is an autonomous coding agent from Nous Research. It works with any OpenAI-compatible endpoint, so FastMetal can be configured as its inference backend directly. Both a CLI and a TUI are included.

Installation

The installer pulls in everything Hermes needs — uv, Python, Node.js, and ripgrep among others.

macOS / Linux / WSL2

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

Windows (PowerShell)

iex (irm https://hermes-agent.nousresearch.com/install.ps1)

Connect with the setup wizard

This is the recommended path. Run the following from your terminal, outside any chat session, and register FastMetal as a custom endpoint.

hermes model

1.Choose "Custom endpoint (self-hosted / VLLM / etc.)".

2.Enter https://api.fastmetal.ai/v1 as the API base URL.

3.Enter your FastMetal API key.

4.Enter a model name from the models page, for example anthropic-claude-sonnet-5.

The wizard also asks for a context length. FastMetal serves model metadata from its /models endpoint, so leaving it blank lets Hermes detect the window automatically. Your answers are persisted to ~/.hermes/config.yaml.

Configure config.yaml directly

You can skip the wizard and edit the config file yourself. Setting provider to custom tells Hermes to call the endpoint at base_url.

~/.hermes/config.yaml

# ~/.hermes/config.yaml
model:
  provider: custom
  base_url: https://api.fastmetal.ai/v1
  default: anthropic-claude-sonnet-5

The API key can go inline in config.yaml, but Hermes recommends keeping secrets in .env. If you omit model.api_key, Hermes falls back to OPENAI_API_KEY.

~/.hermes/.env

# ~/.hermes/.env
OPENAI_API_KEY=your-fastmetal-api-key

Register FastMetal as a named provider

If you juggle several endpoints, give each one a name under providers. Named providers are easier to switch between mid-session, and the name can be reused when assigning auxiliary models.

~/.hermes/config.yaml

# ~/.hermes/config.yaml
providers:
  fastmetal:
    api: https://api.fastmetal.ai/v1
    key_env: FASTMETAL_API_KEY
    transport: chat_completions
    default_model: anthropic-claude-sonnet-5

model:
  provider: custom:fastmetal
  default: anthropic-claude-sonnet-5

~/.hermes/.env

# ~/.hermes/.env
FASTMETAL_API_KEY=your-fastmetal-api-key

FastMetal also exposes an Anthropic-compatible endpoint. To use it, set transport to anthropic_messages. You can register both and switch depending on what you are doing.

~/.hermes/config.yaml

providers:
  fastmetal-anthropic:
    api: https://api.fastmetal.ai/anthropic/v1
    key_env: FASTMETAL_API_KEY
    transport: anthropic_messages
    default_model: anthropic-claude-sonnet-5

Switching models

Use the /model command to change models during a session. For named providers, the syntax is custom:provider:model.

/model custom:fastmetal:glm-5.2
/model custom:fastmetal:deepseek-v4-flash
/model custom:fastmetal:anthropic-claude-opus-5

/model only switches between providers and models you have already configured. To add a new provider, exit the session and run hermes model.

Auxiliary models

Hermes uses separate models for background work — generating conversation titles, compressing history, and interpreting images. Pointing these at cheap, fast models keeps the cost of a long session down.

~/.hermes/config.yaml

auxiliary:
  title_generation:
    provider: fastmetal
    model: gemini-3.5-flash
  compression:
    provider: fastmetal
    model: gemini-3.5-flash
  vision:
    provider: fastmetal
    model: anthropic-claude-sonnet-5

Context length

Hermes normally detects the context window from the endpoint's model metadata. Set it explicitly if detection gets it wrong, or if you want to cap the window below the model's maximum. Hermes uses this value to decide when to compress conversation history.

~/.hermes/config.yaml

model:
  provider: custom:fastmetal
  default: anthropic-claude-sonnet-5
  context_length: 200000

Running Hermes

Once configured, start Hermes. Add --tui for the terminal interface. Every request now routes through FastMetal and is billed against the key you configured.

hermes          # CLI
hermes --tui    # TUI

Operating tips

Issue a dedicated API key for Hermes and set a budget cap on it. The key lives in a config file on disk, so a ceiling bounds what an unexpected loop — or a leaked config — can cost you.

Agents make many requests per task. The usage page breaks actual spend down by model, which is the fastest way to see where a session's cost went.

Not every model holds up in an agentic tool-calling loop. Start with a model known to work well, then experiment once you have a baseline.

Troubleshooting

401 authentication error

The key is not reaching FastMetal. If you are using key_env, confirm that variable is defined in ~/.hermes/.env. To check the key itself, send a request to /v1/models with the same key.

Model not found

Model names must match FastMetal's identifier exactly. Use the name shown on the models page or returned by /models — not the provider's own naming for the same model.

Requests rejected with 429

You have likely exhausted the key's balance. If the response body contains budget_exceeded, top up from the dashboard; requests resume immediately afterwards.