> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs-staging.joytokens.ai/llms.txt.

# Hermes Agent

> Use Hermes Agent with JoyToken

## Prerequisites

| Item                 | Value                   |
| -------------------- | ----------------------- |
| Hermes Agent version | `0.15.2`                |
| Config file          | `~/.hermes/config.yaml` |
| Env file             | `~/.hermes/.env`        |
| Provider             | `joytoken`              |
| Model name           | `auto`                  |
| API key env          | `JOY_TOKEN_API_KEY`     |

Hermes Agent supports both protocols through a named custom provider. Set `transport` to match the selected tab.

## Step 1: Install

```bash
pipx install hermes-agent==0.15.2
hermes --version
```

## Step 2: Set the API key and base URL

#### OpenAI

```bash
export JOY_TOKEN_API_KEY="sk-xxx"
export JOY_TOKEN_OPENAI_BASE_URL="https://api-staging.joytokens.ai/openai/v1"
```

#### Anthropic

```bash
export JOY_TOKEN_API_KEY="sk-xxx"
export JOY_TOKEN_ANTHROPIC_BASE_URL="https://api-staging.joytokens.ai/anthropic/v1"
```

Create `~/.hermes/.env` with the API key and keep the selected base URL in the shell or config file. Restrict the env file permissions:

```bash
mkdir -p ~/.hermes
printf '%s\n' 'JOY_TOKEN_API_KEY="sk-xxx"' > ~/.hermes/.env
chmod 600 ~/.hermes/.env
```

## Step 3: Configure the provider

#### OpenAI

```bash
JOY_TOKEN_OPENAI_BASE_URL="${JOY_TOKEN_OPENAI_BASE_URL:-https://api-staging.joytokens.ai/openai/v1}"
mkdir -p ~/.hermes
cat > ~/.hermes/config.yaml <<EOF
model:
  provider: joytoken
  default: auto

providers:
  joytoken:
    name: JoyToken
    base_url: $JOY_TOKEN_OPENAI_BASE_URL
    key_env: JOY_TOKEN_API_KEY
    default_model: auto
    transport: chat_completions
EOF
```

#### Anthropic

```bash
JOY_TOKEN_ANTHROPIC_BASE_URL="${JOY_TOKEN_ANTHROPIC_BASE_URL:-https://api-staging.joytokens.ai/anthropic/v1}"
mkdir -p ~/.hermes
cat > ~/.hermes/config.yaml <<EOF
model:
  provider: joytoken
  default: auto

providers:
  joytoken:
    name: JoyToken
    base_url: $JOY_TOKEN_ANTHROPIC_BASE_URL
    key_env: JOY_TOKEN_API_KEY
    default_model: auto
    transport: anthropic_messages
EOF
```

## Step 4: Verify

```bash
hermes config check
hermes chat \
  -q "Reply with exactly: pong" \
  --provider joytoken \
  -m auto \
  -Q \
  --ignore-rules
```

A successful response includes `pong`. Hermes may print Python package or security scanner warnings before the response; those warnings do not indicate a failed JoyToken request.

## JoyToken Check

#### OpenAI

| Place | Expected result                               |
| ----- | --------------------------------------------- |
| Logs  | Request path is `/openai/v1/chat/completions` |
| Auth  | Bearer authentication                         |
| Usage | Tokens and credits are recorded               |

#### Anthropic

| Place | Expected result                          |
| ----- | ---------------------------------------- |
| Logs  | Request path is `/anthropic/v1/messages` |
| Auth  | `x-api-key` authentication               |
| Usage | Tokens and credits are recorded          |

## Common Errors

| Error                               | Fix                                                              |
| ----------------------------------- | ---------------------------------------------------------------- |
| `401 Unauthorized`                  | Check `JOY_TOKEN_API_KEY` in `~/.hermes/.env`                    |
| Hermes still calls another provider | Check `model.provider: joytoken` and the selected `transport`    |
| Config check fails                  | Check `providers.joytoken.key_env` and `base_url`                |
| No JoyToken logs                    | Check that the URL and transport match the selected protocol tab |

## Resources

* [JoyToken API Guide](/open-api/api-guides/overview)
* [JoyToken Routing](/user-guide/routing)
* [JoyToken Usage & Billing](/user-guide/usage-billing)