Hermes Agent

Steps to integrate Hermes Agent with Pioneer:

Download and set up Hermes Agent.
Set your Pioneer API key for the one-time setup command:

export PIONEER_API_KEY="<Your Pioneer API key>"

Run this one-time setup command. It fetches the live GET /v1/models catalog, filters out Claude Code discovery aliases, stores your Pioneer API key in Hermes’ local environment file at ~/.hermes/.env, writes the filtered Pioneer provider to ~/.hermes/config.yaml, and sets pioneer/auto as the default model so Pioneer can route each request automatically.

The command requires jq and ruby. It creates a timestamped backup of your existing Hermes config before updating the Pioneer section.

: "${PIONEER_API_KEY:?Set PIONEER_API_KEY first}"

command -v jq >/dev/null || { echo "jq is required"; exit 1; }
command -v ruby >/dev/null || { echo "ruby is required"; exit 1; }

CONFIG_FILE="$(hermes config path)"
CONFIG_TMP="$(mktemp)"
MODELS_JSON="$(mktemp)"
trap 'rm -f "$CONFIG_TMP" "$MODELS_JSON"' EXIT

mkdir -p "$(dirname "$CONFIG_FILE")"
[ -f "$CONFIG_FILE" ] || printf '{}\n' > "$CONFIG_FILE"
cp "$CONFIG_FILE" "$CONFIG_FILE.bak.$(date +%Y%m%d%H%M%S)"

hermes config set PIONEER_API_KEY "$PIONEER_API_KEY"

curl -fsS "https://api.pioneer.ai/v1/models" \
  -H "Authorization: Bearer $PIONEER_API_KEY" \
  | jq '
    def dedupe:
      reduce .[] as $item ([]; if index($item) then . else . + [$item] end);

    def catalog_models:
      (.models // []) as $models
      | if (($models | type) == "array" and ($models | length) > 0) then $models else (.data // []) end;

    def model_id:
      .slug // .id;

    (["pioneer/auto"] + [
      catalog_models[]
      | select(.deprecated != true)
      | model_id
      | select(type == "string" and length > 0)
      # Hide Claude Code discovery aliases so Hermes does not show every model twice.
      | select(startswith("anthropic/") | not)
      | select(. != "pioneer/auto" and . != "auto")
    ]) | dedupe
  ' > "$MODELS_JSON"

ruby -ryaml -rjson -e '
  config_path, models_path, out_path = ARGV
  cfg = File.exist?(config_path) ? (YAML.safe_load(File.read(config_path), aliases: true) || {}) : {}
  abort "#{config_path} must contain a YAML mapping" unless cfg.is_a?(Hash)

  models = JSON.parse(File.read(models_path))
  cfg["providers"] = {} unless cfg["providers"].is_a?(Hash)
  cfg["providers"]["pioneer"] = {
    "name" => "Pioneer",
    "base_url" => "https://api.pioneer.ai/v1",
    "key_env" => "PIONEER_API_KEY",
    "api_mode" => "chat_completions",
    "discover_models" => false,
    "default_model" => "pioneer/auto",
    "models" => models
  }

  cfg["model"] = {} unless cfg["model"].is_a?(Hash)
  cfg["model"]["provider"] = "pioneer"
  cfg["model"]["default"] = "pioneer/auto"
  cfg["model"]["base_url"] = "https://api.pioneer.ai/v1"
  cfg["model"]["api_mode"] = "chat_completions"

  File.write(out_path, YAML.dump(cfg))
' "$CONFIG_FILE" "$MODELS_JSON" "$CONFIG_TMP"

mv "$CONFIG_TMP" "$CONFIG_FILE"
chmod 600 "$CONFIG_FILE"

Start Hermes normally:

hermes

Switch between saved Pioneer models with /model inside Hermes. Use --global when you want the change to persist in ~/.hermes/config.yaml:

/model
/model claude-opus-4-8 --provider pioneer
/model gpt-5.5 --provider pioneer --global
/model pioneer/auto --provider pioneer --global

hermes model is Hermes’ full provider setup wizard. /model inside an active Hermes session only switches between providers you have already configured. The setup above configures a named pioneer provider, so /model can switch among saved Pioneer models without re-entering your API key.

The model list is pulled when you run the setup command. Re-run the setup command when you want Hermes to pick up newly added Pioneer models. The command sets discover_models: false because Pioneer’s live catalog also includes anthropic/* aliases for Claude Code, which would otherwise make Hermes show duplicate rows.

Verify setup

Run a quick non-interactive check:

hermes chat -q "Reply with exactly PIONEER_HERMES_OK"

Or inspect the filtered catalog directly:

curl -fsS "https://api.pioneer.ai/v1/models" \
  -H "Authorization: Bearer $PIONEER_API_KEY" \
  | jq -r '
    def catalog_models:
      (.models // []) as $models
      | if (($models | type) == "array" and ($models | length) > 0) then $models else (.data // []) end;

    catalog_models[]
    | (.slug // .id)
    | select(type == "string" and length > 0)
    | select(startswith("anthropic/") | not)
  ' \
  | head

After setup, Hermes reads PIONEER_API_KEY from ~/.hermes/.env, so you do not need to export it in every terminal. Keep exporting it only when you want to run shell commands like the catalog check above.

Troubleshooting

/model does not show Pioneer models

Re-run the setup command above, then restart Hermes. The setup writes both the named provider and the filtered providers.pioneer.models list that /model reads.Confirm the active provider:

hermes config show

Make sure Model shows provider: pioneer, then start a new Hermes session. If you are already inside a Hermes session, /model can switch models but cannot run the full provider setup wizard.

Pioneer models appear twice

Re-run the setup command above. The duplicate entries are Claude Code discovery aliases from the raw Pioneer catalog, such as anthropic/pioneer/gpt-5.5. Hermes does not filter generic live discovery in v0.18, so the setup stores a filtered list and sets providers.pioneer.discover_models to false.

Hermes says the Pioneer API key is missing

Store the key again:

export PIONEER_API_KEY="<Your Pioneer API key>"
hermes config set PIONEER_API_KEY "$PIONEER_API_KEY"

Hermes stores API keys in ~/.hermes/.env, not directly in config.yaml.

How to undo the Pioneer setup

Switch Hermes back to the provider you want:

hermes model

Or set another provider directly:

hermes config set model.provider openrouter
hermes config set model.default anthropic/claude-sonnet-4

Get Started

Integrations

Core Concepts

API Reference

Guides

Account

Verify setup

Troubleshooting

​Verify setup

​Troubleshooting

Verify setup

Troubleshooting