Running Hermes on Claude Sonnet 4.6: Provider Setup and OAuth Sharing with Claude Code

Once Hermes is installed, the first meaningful decision is how it talks to Claude. The default answer — Anthropic provider with Claude Sonnet 4.6 as the model — is almost always right. The interesting detail is that Hermes integrates with Claude Code's existing credential store, so a Pro or Max account you already pay for carries over without extra setup.

This article covers provider configuration, the claude and claude-code aliases, OAuth sharing, and a sensible fallback strategy so a momentary outage does not take your agent down.

Key Takeaways

• Hermes uses anthropic>=0.39.0 as a core Python dependency, so Claude is first-class.
• The canonical config sets provider: anthropic and default: claude-sonnet-4-6 in ~/.hermes/config.yaml.
• Model aliases claude and claude-code both resolve to the same Anthropic provider path.
• Hermes reads the Claude Code credential store directly, so your existing Pro or Max OAuth works without copying tokens.
• A fallback model chain keeps the agent responsive during rate limits or provider blips.
• Provider configuration can also be set via hermes model CLI commands or environment variables.
• This is the natural next step after installing Hermes on a $5 VPS.

The Config File

Everything lives in ~/.hermes/config.yaml. The minimum viable configuration for Claude Sonnet 4.6 is three lines:

model:
  provider: "anthropic"
  default: "claude-sonnet-4-6"

That is it. On first launch Hermes will look for an ANTHROPIC_API_KEY environment variable, or, if you are running on a machine where Claude Code is already authenticated, it will fall back to the Claude Code credential store.

For API key authentication:

export ANTHROPIC_API_KEY=sk-ant-***
hermes chat --provider anthropic --model claude-sonnet-4-6

That command launches an interactive session backed by Sonnet 4.6 with the full Hermes tool surface available.

Why Claude Sonnet 4.6 Is the Right Default

Hermes is a tool-heavy runtime. It expects the underlying model to handle long tool-use chains, stay coherent across multi-step plans, and format structured output reliably. Sonnet 4.6 hits that sweet spot of coding quality and throughput without the per-token cost of Opus. For research-grade reasoning tasks you can override on a per-session basis, but for 90% of automated workflows Sonnet 4.6 is the default for a reason.

The claude and claude-code Aliases

Hermes accepts two aliases for the Anthropic provider that will feel familiar:

hermes chat --provider claude --model claude-sonnet-4-6
hermes chat --provider claude-code --model claude-sonnet-4-6

Both are equivalent to --provider anthropic. The aliases exist because Claude Code users type claude reflexively, and because the claude-code provider also implies the delegation behaviors baked into the bundled skills/autonomous-ai-agents/claude-code/SKILL.md skill. Functionally for a direct chat, they are the same path.

Credential Sharing with Claude Code

This is the quality-of-life feature most Claude Code users wish existed in more tools. If Claude Code is already installed and logged in on the same machine (your VPS, your workstation, a dev container), Hermes can read that credential store directly. No tokens to copy, no duplicate OAuth dance, no risk of leaking keys in environment files.

Workflow on a fresh VPS:

# Install Claude Code if not already present
curl -fsSL https://claude.ai/install.sh | bash
claude login
# complete the OAuth flow once

# Now Hermes can reuse those credentials
hermes chat --provider anthropic --model claude-sonnet-4-6

If your Anthropic relationship is a Pro or Max subscription rather than raw API credit, this is the path you want. Hermes usage counts against the same quota as Claude Code in that configuration, which is usually preferable for solo operators.

To explicitly disable credential sharing and force API key usage, set an empty Claude Code credential path in your config:

model:
  provider: "anthropic"
  default: "claude-sonnet-4-6"
  credentials:
    claude_code: false

Fallback Models

Even the best provider has the occasional hiccup. A fallback chain protects long-running cron jobs from a 429 or a regional incident. Hermes supports a list under model.fallbacks:

model:
  provider: "anthropic"
  default: "claude-sonnet-4-6"
  fallbacks:
    - provider: "anthropic"
      model: "claude-opus-4-1"
    - provider: "openai"
      model: "gpt-4.1"

The first fallback stays within Anthropic but drops to a different model (useful for capacity issues on a specific Sonnet tier). The second crosses provider lines for resilience during a broader Anthropic incident. Hermes will burn a retry on the default, then walk the chain.

For budget-sensitive deployments, flip the order: put a cheaper model like Haiku as the default for a specific skill and escalate to Sonnet 4.6 only when needed. We dig into cost control patterns in cost control: Hermes max turns, budget, fallback.

Changing the Model Mid-Session

The hermes model CLI command lets you inspect or switch providers without editing YAML:

hermes model list
hermes model set anthropic claude-sonnet-4-6
hermes model current

Inside an active chat session, you can also swap models with a /model slash command, which is helpful when you want to run a planning step on Opus and then drop back to Sonnet for execution.

Per-Skill Model Overrides

SKILL.md files can request a specific model in their frontmatter. If a skill says it wants Opus for a reasoning-heavy step, Hermes will honor that for the duration of the skill's execution, then return to the configured default. This is especially useful for meta skills like planning and code review, where the extra cost pays for itself.

Verifying Your Setup

A quick sanity check that your provider, model, and credentials all work:

hermes chat --provider anthropic --model claude-sonnet-4-6 \
  --message "Echo back the model name you are running on."

You should see claude-sonnet-4-6 in the response. If you get an authentication error, the credential store or API key is not being picked up — run hermes doctor for a diagnostic.

What Is Next

You now have Hermes pointed at the right model and authenticated in the right way. The next step is to write something bespoke: a SKILL.md that encodes a procedure you run every week. That is the topic of writing your first Hermes SKILL.md. For the conceptual foundation on how Hermes remembers between sessions, see the Hermes memory deep dive.

Sources

• Hermes Agent GitHub repository
• Hermes Agent documentation
• Anthropic Claude Code docs
• What is Hermes Agent?
• Installing Hermes Agent on a $5 VPS
• Writing your first Hermes SKILL.md