Hermes Agent | JoyToken | Documentation

Prerequisites

Item	Value
Hermes Agent version	`0.15.2`
Config file	`~/.hermes/config.yaml`
Env file	`~/.hermes/.env`
Provider	`joytoken`
Model name	`auto`
JoyToken Base URL	`JOY_TOKEN_OPENAI_BASE_URL` from Environments
API key env	`JOY_TOKEN_API_KEY`

Step 1: Install

$ pipx install hermes-agent==0.15.2
$ hermes --version

Step 2: Write the API key

Replace jt_xxx with your JoyToken API key, then run:

Write ~/.hermes/.env

$ JOY_TOKEN_API_KEY="jt_xxx"
$ JOY_TOKEN_OPENAI_BASE_URL="https://api-dev.joytokens.ai/openai/v1"
$ 
$ mkdir -p ~/.hermes
$ printf '%s\n' "JOY_TOKEN_API_KEY=\"${JOY_TOKEN_API_KEY}\"" > ~/.hermes/.env
$ chmod 600 ~/.hermes/.env

The command writes this file content with the concrete value from JOY_TOKEN_OPENAI_BASE_URL:

~/.hermes/.env

$ JOY_TOKEN_API_KEY="jt_xxx"

Step 3: Configure provider

Run this command to write the Hermes provider config:

Write ~/.hermes/config.yaml

$ JOY_TOKEN_OPENAI_BASE_URL="${JOY_TOKEN_OPENAI_BASE_URL:-https://api-dev.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

The command writes this file content:

~/.hermes/config.yaml

1 model:
2   provider: joytoken
3   default: auto
4 
5 providers:
6   joytoken:
7     name: JoyToken
8     base_url: <JOY_TOKEN_OPENAI_BASE_URL>
9     key_env: JOY_TOKEN_API_KEY
10     default_model: auto
11     transport: chat_completions

Step 4: Verify

$ hermes config check

Run one request:

$ hermes chat \
>   -q "Reply with exactly: pong" \
>   --provider joytoken \
>   -m auto \
>   -Q \
>   --ignore-rules

A successful response includes pong.

Hermes may also print Python package or security scanner warnings before the response. If the output includes pong, the JoyToken request succeeded.

JoyToken Check

Place	Expected result
Logs	Request path is `/openai/v1/chat/completions`
API key	Request is attributed to the key used by Hermes
Usage	Tokens and credits are recorded
Model	Requested model is `auto`

Common Errors

Error	Fix
`401 Unauthorized`	Check `JOY_TOKEN_API_KEY` in `~/.hermes/.env`
Hermes still calls another provider	Check `model.provider: joytoken` in `~/.hermes/config.yaml`
Config check fails	Check that `providers.joytoken.key_env` is `JOY_TOKEN_API_KEY`
No JoyToken logs	Check that `base_url` is the JoyToken OpenAI-compatible URL