Lewati ke konten
8Labs.
Blog
Client Panel

Install & Run Hermes Agent on IPv6-only VPS

Konten ini belum tersedia dalam bahasa Anda.

Artikel ini belum diterjemahkan. Isi berikut berbahasa Inggris. Buka versi asli bahasa Inggris.

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

Section titled “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

Section titled “Dependency IPv6 Status”

| Service | Endpoint | IPv6 | Impact | | ----------------- | ------------------------------------- | ------------- | ----------------------------- | -------------------- | | Install script | raw.githubusercontent.com | ✅ Native | curl | bash works directly | | 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

Section titled “Install Paths”

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

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

Section titled “Step 1: Install”
Terminal window
# 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

Section titled “Step 2: Verify”
Terminal window
hermes doctor
hermes --version

Step 3: Configure Provider

Section titled “Step 3: Configure Provider”
Terminal window
# 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-..."

Step 4: Run

Section titled “Step 4: Run”
Terminal window
hermes
# or single query
hermes chat -q "What can you do?"

Ongoing Operations

Section titled “Ongoing Operations”

Updates

Section titled “Updates”
Terminal window
# git pull uses the hosts-file proxy — works transparently
hermes update

Skills & Plugins

Section titled “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:

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

Gateway (Messaging Platforms)

Section titled “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:

Terminal window
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

Section titled “What Works vs What Doesn’t”

✅ Works on IPv6-only (no changes needed)

Section titled “✅ Works on IPv6-only (no changes needed)”

| Component | Why | | ----------------------------------- | ------------------------------------- | ------------------------------------------- | | Install script (curl | bash) | raw.githubusercontent.com has native IPv6 | | 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

Section titled “❌ Needs workaround”
ComponentIssueFix
git clone from GitHubNo AAAAIPv6 proxy in /etc/hosts (Solution 1)
ghcr.io container pullsNo AAAANAT64/DNS64 (Solution 3) or proxy
OpenAI API directlyNo AAAAOpenRouter gateway or NAT64 (Solution 4)

Troubleshooting

Section titled “Troubleshooting”
SymptomCauseFix
curl | bash hangsraw.githubusercontent.com DNS issueVerify AAAA: dig AAAA raw.githubusercontent.com
Install fails at git cloneGitHub proxy not configuredCheck /etc/hosts has GitHub entries
hermes update failsGit cannot reach github.comVerify proxy: curl -I https://github.com
docker pull ghcr.io/... hangsghcr.io has no IPv6Enable NAT64 or add ghcr.io to /etc/hosts
OpenAI models return errorsDirect api.openai.com unreachableSwitch to OpenRouter or enable NAT64
Skills install failsGitHub proxy not workingTest: git ls-remote https://github.com/NousResearch/hermes-agent.git

References

Section titled “References”

Community Resources

Section titled “Community Resources”