|
| 1 | +# Hermes Agent |
| 2 | + |
| 3 | +[Hermes Agent](https://github.com/NousResearch/hermes-agent) by Nous Research supports ACP natively via the `hermes acp` subcommand (or the `hermes-acp` binary). |
| 4 | + |
| 5 | +Hermes acts as a multi-provider inference gateway — it handles OAuth token lifecycle, credential storage, and provider routing so OAB agents don't need to manage auth directly. |
| 6 | + |
| 7 | +## Docker Image |
| 8 | + |
| 9 | +```bash |
| 10 | +docker build -f Dockerfile.hermes -t openab-hermes:latest . |
| 11 | +``` |
| 12 | + |
| 13 | +The image installs Hermes Agent via the official install script. |
| 14 | + |
| 15 | +## Helm Install |
| 16 | + |
| 17 | +```bash |
| 18 | +helm install openab openab/openab \ |
| 19 | + --set agents.kiro.enabled=false \ |
| 20 | + --set agents.hermes.discord.enabled=true \ |
| 21 | + --set agents.hermes.discord.botToken="$DISCORD_BOT_TOKEN" \ |
| 22 | + --set-string 'agents.hermes.discord.allowedChannels[0]=YOUR_CHANNEL_ID' \ |
| 23 | + --set agents.hermes.image=ghcr.io/openabdev/openab-hermes:latest \ |
| 24 | + --set agents.hermes.command=hermes-acp \ |
| 25 | + --set agents.hermes.workingDir=/home/agent |
| 26 | +``` |
| 27 | + |
| 28 | +> Set `agents.kiro.enabled=false` to disable the default Kiro agent. |
| 29 | +
|
| 30 | +## Manual config.toml |
| 31 | + |
| 32 | +```toml |
| 33 | +[agent] |
| 34 | +command = "hermes-acp" |
| 35 | +working_dir = "/home/agent" |
| 36 | +``` |
| 37 | + |
| 38 | +## Authentication |
| 39 | + |
| 40 | +Hermes supports 30+ providers. Authenticate inside the pod: |
| 41 | + |
| 42 | +```bash |
| 43 | +kubectl exec -it <pod> -- hermes auth add xai-oauth # xAI Grok (SuperGrok $30/mo) |
| 44 | +kubectl exec -it <pod> -- hermes auth add nous # Nous Portal |
| 45 | +kubectl exec -it <pod> -- hermes model # Interactive provider picker |
| 46 | +``` |
| 47 | + |
| 48 | +### xAI Grok OAuth (Recommended) |
| 49 | + |
| 50 | +> ⚠️ **Requires an active [SuperGrok paid subscription](https://x.ai/grok) ($30/mo).** Auth will succeed without one, but the API silently returns empty responses — the bot appears to work but never replies. |
| 51 | +
|
| 52 | +xAI Grok OAuth uses a loopback redirect flow — the callback listener binds `127.0.0.1:56121` inside the pod. You need a port-forward so your browser's redirect reaches the pod: |
| 53 | + |
| 54 | +```bash |
| 55 | +# Terminal 1: port-forward |
| 56 | +kubectl port-forward deployment/<your-deployment> 56121:56121 |
| 57 | + |
| 58 | +# Terminal 2: run auth |
| 59 | +kubectl exec -it deployment/<your-deployment> -- hermes auth add xai-oauth --no-browser |
| 60 | +``` |
| 61 | + |
| 62 | +1. Copy the printed authorize URL → open in your local browser |
| 63 | +2. Approve access on accounts.x.ai |
| 64 | +3. Browser redirects to `127.0.0.1:56121/callback` → port-forward delivers it to the pod |
| 65 | +4. Terminal shows "Login successful!" |
| 66 | + |
| 67 | +After auth, set the default model: |
| 68 | + |
| 69 | +```bash |
| 70 | +kubectl exec <pod> -- hermes config set model.provider xai-oauth |
| 71 | +kubectl exec <pod> -- hermes config set model.default grok-4.3 |
| 72 | +``` |
| 73 | + |
| 74 | +> **Note:** Tokens are stored in `~/.hermes/auth.json` and auto-refresh in the background. |
| 75 | +
|
| 76 | +### Providers That Don't Need Port-Forward |
| 77 | + |
| 78 | +| Provider | Auth Method | |
| 79 | +|----------|-------------| |
| 80 | +| Anthropic (Claude Pro/Max) | Paste-the-code flow | |
| 81 | +| OpenAI Codex (ChatGPT Plus/Pro) | Device code flow | |
| 82 | +| MiniMax, Nous Portal | Device code flow | |
| 83 | +| xAI Grok, Spotify | Loopback OAuth (port-forward required) | |
| 84 | + |
| 85 | +### Supported Providers (via OAuth) |
| 86 | + |
| 87 | +| Provider | Auth Command | Cost Model | |
| 88 | +|----------|-------------|------------| |
| 89 | +| xAI Grok | `hermes auth add xai-oauth` | SuperGrok subscription ($30/mo) | |
| 90 | +| OpenAI Codex | `hermes model` → OpenAI Codex | ChatGPT subscription | |
| 91 | +| GitHub Copilot | `hermes model` → GitHub Copilot | Copilot subscription | |
| 92 | +| Google Gemini | `hermes model` → Google Gemini (OAuth) | Free tier available | |
| 93 | +| Anthropic | `hermes model` → Anthropic | Claude Max + extra credits | |
| 94 | +| Nous Portal | `hermes auth add nous` | Nous subscription | |
| 95 | + |
| 96 | +### Supported Providers (via API Key) |
| 97 | + |
| 98 | +Any provider can also be configured with an API key via environment variables: |
| 99 | + |
| 100 | +```toml |
| 101 | +[agent] |
| 102 | +command = "hermes-acp" |
| 103 | +working_dir = "/home/agent" |
| 104 | +env = { XAI_API_KEY = "${XAI_API_KEY}" } |
| 105 | +``` |
| 106 | + |
| 107 | +## Provider Switching |
| 108 | + |
| 109 | +Switch providers without restarting the pod: |
| 110 | + |
| 111 | +```bash |
| 112 | +kubectl exec -it <pod> -- hermes model |
| 113 | +``` |
| 114 | + |
| 115 | +## Credential Persistence |
| 116 | + |
| 117 | +Hermes stores OAuth tokens in `~/.hermes/`. The OpenAB Helm chart's default persistence covers this automatically (PVC mounted at `workingDir`). |
| 118 | + |
| 119 | +If deploying manually (without the Helm chart), mount persistent storage at `/home/agent` or `/home/agent/.hermes`: |
| 120 | + |
| 121 | +```yaml |
| 122 | +volumes: |
| 123 | + - name: hermes-credentials |
| 124 | + persistentVolumeClaim: |
| 125 | + claimName: hermes-credentials-pvc |
| 126 | +volumeMounts: |
| 127 | + - name: hermes-credentials |
| 128 | + mountPath: /home/agent/.hermes |
| 129 | +``` |
| 130 | +
|
| 131 | +## Advantages |
| 132 | +
|
| 133 | +- **Cost**: SuperGrok $30/mo flat rate vs pay-per-token API pricing |
| 134 | +- **Multi-provider**: 30+ providers accessible through one agent |
| 135 | +- **Zero auth complexity**: Hermes handles OAuth + token refresh |
| 136 | +- **Multi-modal**: TTS, image gen, video gen via the same OAuth token |
| 137 | +- **Fallback chains**: Auto-switch providers on failure |
0 commit comments