Install & Run Hermes Agent on IPv6-only VPS

Hermes Agent is an open-source AI agent framework by Nous Research. It needs GitHub (git clone) and optionally GitHub Container Registry (ghcr.io) — both of which lack IPv6. This guide covers a complete install and operational setup on an IPv6-only VPS, drawing on the solutions from the general IPv6 tutorial.

Prerequisites

Complete the general IPv6 tutorial first so that:

• GitHub is reachable via IPv6 proxy or NAT64/DNS64
• Docker Hub works (if using the containerised install path)

This page assumes those are already in place.

Dependency IPv6 Status

Service	Endpoint	IPv6	Impact
Install script	raw.githubusercontent.com	✅ Native	`curl
Git clone	github.com	❌	Needs proxy or NAT64
Python packages	pypi.org / files.pythonhosted.org	✅ Fastly	pip / uv works directly
npm packages	registry.npmjs.org	✅ Cloudflare	npm works directly
Container images	ghcr.io	❌	Needs NAT64 or proxy
LLM — OpenAI	api.openai.com	❌	Use OpenRouter or NAT64
LLM — most others	Various	✅	Anthropic, Groq, Gemini, etc.

---

Install Paths

Two supported paths, both work on IPv6-only after the prerequisites above.

Native Install (Python + Node)

The standard one-liner works because raw.githubusercontent.com has native IPv6. The install script’s git clone step uses the GitHub host mappings you already set up in /etc/hosts.

Step 1: Install

# curl fetches the script over IPv6 (raw.githubusercontent.com)
# git clone uses /etc/hosts IPv6 proxy
curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash

If the install script prompts for uv installation, answer yes — uv fetches from PyPI which has native IPv6.

Step 2: Verify

hermes doctor
hermes --version

Step 3: Configure Provider

# OpenRouter (IPv6-native, recommended)
hermes config set model.provider openrouter
hermes config set model.default "openai/gpt-4o"

# Or direct Anthropic (IPv6-native)
hermes config set model.provider anthropic
hermes config set model.default "claude-sonnet-4-20250514"

Set your API keys in ~/.hermes/.env:

~/.hermes/.env

OPENROUTER_API_KEY="sk-or-..."
# or
ANTHROPIC_API_KEY="sk-ant-..."

Tip

For the smoothest IPv6-only experience, use OpenRouter as your primary provider. It has native IPv6 (Cloudflare) and proxies 200+ models including OpenAI, Anthropic, Google, Meta, and DeepSeek — all through a single IPv6 endpoint.

Step 4: Run

hermes
# or single query
hermes chat -q "What can you do?"

Docker / s6 Container

The containerised install uses ghcr.io/nousresearch/hermes-agent — GitHub Container Registry, which has no IPv6.

Step 1: Enable NAT64 or ghcr.io proxy

Option A — NAT64 (recommended)

Docker daemon respects the host’s DNS64 configuration. With NAT64 + DNS64 enabled:

# Pull works — DNS64 translates ghcr.io to IPv6
docker pull ghcr.io/nousresearch/hermes-agent:latest

Option B — DanWin1210 ghcr.io proxy

Add to /etc/hosts:

/etc/hosts

2a01:4f8:c010:d56::6 ghcr.io

Then:

docker pull ghcr.io/nousresearch/hermes-agent:latest

Step 2: Run via s6

Follow the standard Hermes s6 container guide:

docker run -d \
  --name hermes-agent \
  -v ~/.hermes:/home/hermes/.hermes \
  -v /var/run/docker.sock:/var/run/docker.sock \
  ghcr.io/nousresearch/hermes-agent:latest

---

Ongoing Operations

Updates

# git pull uses the hosts-file proxy — works transparently
hermes update

Skills & Plugins

Skills and plugins are fetched via git clone from GitHub. Since GitHub is already reachable through the proxy setup in the prerequisites, both work:

hermes skills install <skill-id>
hermes plugins install <plugin-name>

Gateway (Messaging Platforms)

The gateway connects to Telegram, Discord, and other platforms. These platforms use their own infrastructure — they are not affected by the IPv6-only constraint:

hermes gateway setup
hermes gateway run

~/.hermes/.env

TELEGRAM_BOT_TOKEN="..."

The gateway will connect to Telegram’s API natively (Telegram supports IPv6).

---

What Works vs What Doesn’t

✅ Works on IPv6-only (no changes needed)

Component	Why
Install script (`curl	bash`)
pip / uv packages	PyPI + Fastly dual-stack
npm packages	npm registry via Cloudflare
OpenRouter API	Cloudflare IPv6
Anthropic API	Native IPv6
Google Gemini API	Native IPv6
Groq, Mistral, DeepSeek, Perplexity	Native IPv6 via Cloudflare/CloudFront
Telegram/Discord gateway	Platform APIs are IPv6-ready
Docker Hub pulls	Native IPv6 (registry-1.docker.io)

❌ Needs workaround

Component	Issue	Fix
git clone from GitHub	No AAAA	IPv6 proxy in /etc/hosts (Solution 1)
ghcr.io container pulls	No AAAA	NAT64/DNS64 (Solution 3) or proxy
OpenAI API directly	No AAAA	OpenRouter gateway or NAT64 (Solution 4)

---

Troubleshooting

Symptom	Cause	Fix
curl | bash hangs	raw.githubusercontent.com DNS issue	Verify AAAA: dig AAAA raw.githubusercontent.com
Install fails at git clone	GitHub proxy not configured	Check /etc/hosts has GitHub entries
hermes update fails	Git cannot reach github.com	Verify proxy: curl -I https://github.com
docker pull ghcr.io/... hangs	ghcr.io has no IPv6	Enable NAT64 or add ghcr.io to /etc/hosts
OpenAI models return errors	Direct api.openai.com unreachable	Switch to OpenRouter or enable NAT64
Skills install fails	GitHub proxy not working	Test: git ls-remote https://github.com/NousResearch/hermes-agent.git

---

References

• Hermes Agent Docs
• Hermes Agent GitHub
• IPv6 Tutorial (prerequisites for this guide)
• OpenRouter API Docs
• Google DNS64

Community Resources

• So you got an IPv6-only VPS? — Practical blog about living with an IPv6-only server, including NAT64 setup and service compatibility
• How to get IPv4 connectivity on an IPv6 only VPS — GitHub Gist with comprehensive NAT64/DNS64 and proxy workarounds
• OpenAI API endpoint does NOT support IPv6 — r/ipv6 community discussion confirming the issue and sharing workarounds
• An IPv6-only VPS that costs less — Hacker News discussion (80 comments) on IPv6-only hosting experiences