Skip to main content

Run Hermes on any model

Nous Research's agent framework - add your Antseed gateway as a provider, or let Hermes set itself up.

Autonomous agentsOpenAI Chat Completions~5 min

What Hermes is. Hermes Agent is the open-source agent framework from Nous Research. It runs as a long-lived gateway (Telegram, Discord, Slack, …) and reads its model provider from its config.

Fastest path: let Hermes do it. Install the hermes-antseed skill and tell your agent "set yourself up to run on Antseed". It snapshots its config, uses your gateway or, if you have none, sets one up on this computer as a background service with a key just for Hermes, checks your balance, tests which models actually answer, adds Antseed next to your current provider, switches only after a passing test, and asks you to send /restart.

Doing it by hand is the same steps below. Use hermes config set for every change instead of pasting YAML: your config.yaml already has a model: block, and a second one breaks it.

Run Antseed first

Every integration needs an Antseed endpoint: a gateway, best on a small server so every tool on every machine can reach it, or the local buyer proxy (same computer only). One-time setup, a few minutes.

Before you start

Prerequisites

  • Hermes installed and answering (hermes -z "hi" replies).
  • An Antseed endpoint. Recommended: a gateway, with its base URL (ending in /v1) and an API key from its console, and a funded workspace wallet. It works wherever Hermes runs. No gateway yet: the skill (Option A) sets one up on this computer, or see "No gateway yet" in Configure. Alternative, only when Hermes runs on the same computer: the local buyer proxy (the desktop app, or antseed buyer start), funded (antseed buyer balance shows Available above 0).

Step 1

Install Hermes

  • Option A: install the skill and let Hermes set itself up
    hermes skills install Antseed/antseed/skills/hermes-antseed

    Then message your agent: "Set yourself up to run on Antseed using the hermes-antseed skill." Without a gateway, it installs the Antseed CLI and runs antseed gateway service install, then creates a key for itself and saves it in ~/.antseed/hermes/api-key, a file only you can read. It stops to ask you if the wallet needs funds, and finishes by asking you to send /restart. Skip the rest of this page.

  • Option B (by hand): snapshot your config and note your current model
    hermes backup --quick --label before-antseed hermes config get model.provider hermes config get model.default

    Undo later from chat with /snapshot restore <id> (the id the backup prints), then /restart.

Step 2

Point Hermes at Antseed

No gateway yet: run one on this computer in the background

npm install -g @antseed/cli@latest --allow-scripts=@antseed/node,better-sqlite3,node-datachannel antseed gateway service install antseed gateway key create --label hermes

Installs the gateway, and the buyer it needs, as a background service that starts at login and restarts if it stops: a launchd agent on macOS, a systemd user service on Linux, no root needed. --allow-scripts lets recent npm versions build the CLI's native modules. Use http://localhost:8379/v1 as ANTSEED_BASE_URL and the printed key as ANTSEED_API_KEY. Check it later with antseed gateway service status; remove it with antseed gateway service uninstall. On a Linux server, run the loginctl enable-linger command it prints to keep it running after you log out. With encrypted wallet keys, set ANTSEED_PASSPHRASE_FILE before installing: the service can't ask for the passphrase.

Recommended: a gateway

ANTSEED_BASE_URLhttps://gateway.example.com/v1
ANTSEED_API_KEYantseed_…
Show as shell exports
export ANTSEED_BASE_URL="https://gateway.example.com/v1" export ANTSEED_API_KEY="antseed_…"

Your gateway's base URL, ending in /v1, and an API key from the Keys page of its console. Recommended: a gateway on a server, which every machine can reach. A gateway on this computer is http://localhost:8379/v1; publish it with a tunnel (antseed tunnel start) for other machines. No gateway yet: see Run Antseed first above. Same computer as the buyer, no gateway: use http://127.0.0.1:8377/v1 and the placeholder key antseed-p2p; the local proxy checks no key. The commands below read both variables, so they work either way.

# Text models on the network right now (ids are case-sensitive): curl -s "$ANTSEED_BASE_URL/models?type=text" -H "Authorization: Bearer $ANTSEED_API_KEY" | jq -r '.data[].id' try_model() { curl -s -m 90 "$ANTSEED_BASE_URL/chat/completions" \ -H 'Content-Type: application/json' -H "Authorization: Bearer $ANTSEED_API_KEY" \ -d "{\"model\":\"$1\",\"stream\":false,\"max_tokens\":64,\"messages\":[{\"role\":\"user\",\"content\":\"Reply with: ok\"}]}" \ | grep -q '"choices"' && echo "OK $1" || echo "FAIL $1" } # Candidates, strongest first. Replace with ids from the list above: models="kimi-k3 kimi-k2.6 glm-5.1 minimax-m2.7 deepseek-v4-flash" for m in $models; do try_model "$m"; done

Take ids from the list, not from memory: they change over time. max_tokens is 64 so reasoning models have room to answer. Pick models that actually answer right now. Listed in /v1/models is not the same as servable: a model can be listed while no seller your routing policy allows serves it. A 402 / insufficient_deposits means the wallet needs funds: the workspace wallet in the gateway console (Wallet & Funding), or antseed buyer deposit for a local buyer. The test is non-streaming on purpose, because Hermes' helper calls (titles, compression) are non-streaming. Use the first OK as your main model and a cheap OK one (minimax-m2.7, deepseek-v4-flash) as the helper. Each test costs a fraction of a cent.

hermes config set ANTSEED_API_KEY "$ANTSEED_API_KEY" hermes config set providers.antseed.name Antseed hermes config set providers.antseed.base_url "$ANTSEED_BASE_URL" hermes config set providers.antseed.key_env ANTSEED_API_KEY hermes config set providers.antseed.api_mode chat_completions hermes config set providers.antseed.default_model kimi-k3 # Test it before switching (your current provider is still the default): hermes -z "Reply with exactly: antseed-ok" --provider antseed -m kimi-k3

Adds Antseed next to your current provider. ANTSEED_API_KEY goes into Hermes' .env. Replace kimi-k3 with your main model from the test above. It must print antseed-ok before you continue.

# Save the 8 settings this step changes, to undo it exactly: mkdir -p "$HOME/.antseed" for k in model.provider model.default model.base_url model.api_mode \ auxiliary.title_generation.provider auxiliary.title_generation.model \ auxiliary.compression.provider auxiliary.compression.model; do if v="$(hermes config get "$k" 2>/dev/null </dev/null)"; then printf 'set\t%s\t%s\n' "$k" "$v"; else printf 'unset\t%s\n' "$k"; fi done > "$HOME/.antseed/hermes-before-antseed.tsv" cat "$HOME/.antseed/hermes-before-antseed.tsv" hermes config set model.provider antseed hermes config set model.default kimi-k3 hermes config set model.base_url "" hermes config set model.api_mode chat_completions hermes config set auxiliary.title_generation.provider antseed hermes config set auxiliary.title_generation.model minimax-m2.7 hermes config set auxiliary.compression.provider antseed hermes config set auxiliary.compression.model minimax-m2.7 hermes -z "Reply with exactly: default-ok"

Makes Antseed the default. If it does not print default-ok, put all 8 settings back with the next block.

# Only if default-ok failed: restore the saved settings while IFS=$'\t' read -r state k v; do if [ "$state" = set ]; then hermes config set "$k" "$v" </dev/null; else hermes config unset "$k" </dev/null 2>/dev/null || true; fi done < "$HOME/.antseed/hermes-before-antseed.tsv" hermes -z "Reply with exactly: restored-ok"

Puts back each setting exactly as it was, including ones that were not set before. It must print restored-ok. If it does not, send /snapshot restore <id> in chat (the id from the backup), then /restart.

Step 3

Pick a model

kimi-k3glm-5.1deepseek-v4-prominimax-m2.7deepseek-v4-flash

Use a concrete model id that passed the test above. Do not use the id antseed: it follows the buyer's default route (set with POST /_antseed/route), so it only works against the local buyer proxy, never through a gateway.

The full list is every model on the network. Run GET /v1/models on your endpoint, antseed network browse, or open the live network page to see what's available right now.

Verify

Test it

  • Reload Hermes: send /restart in your Hermes chat
    /restart

    The running gateway only picks up the new model and the ANTSEED_API_KEY it reads from .env after a restart. /restart lets the current reply finish first. From a terminal instead: hermes gateway restart. Terminal-only use needs nothing: the next hermes session reads the new config.

  • Confirm requests are flowing and being paid
    curl -s "$ANTSEED_BASE_URL/key" -H "Authorization: Bearer $ANTSEED_API_KEY"

    On a gateway, GET /v1/key shows the key's usage and limits, and the console's Logs page lists each request with its seller and cost. With the local buyer proxy, run antseed buyer metering (per-peer tokens and USDC) and antseed buyer balance (Available vs Reserved) instead. The first request to a seller opens a payment channel (~5–15s on Base).

How Hermes talks to Antseed

  • Wire format sent by Hermes: OpenAI Chat Completions (hits /v1/chat/completions on your gateway or buyer proxy)
  • Best-fit services: any service whose protocols array contains openai-chat-completions. That's what the peer advertises as natively-supported - zero translation overhead, no transform edge cases.
  • How to check a peer: run antseed network peer <peerId> --json and look at providerServiceApiProtocols[provider].services[service]. The browse command exposes the same field per peer.
  • What happens when protocols don't match: Antseed's @antseed/api-adapter translates between OpenAI Chat Completions and the service's native protocol on the fly, inside the buyer. So a request from Hermes can still reach a service that only advertises anthropic-messages - just with a small transform step.
  • One known caveat: services whose only advertised protocol is openai-responses require streaming. If Hermes sends a non-streaming request and Antseed routes it to one of those services, the call fails with HTTP 400: Stream must be set to true. Pick a service whose protocols includes openai-chat-completions (or another non-responses protocol) to avoid this.

If it goes wrong

Troubleshooting

  • no_default_routeThe model id antseed routes to the buyer's default route, and none is set. Use a concrete id from the model test.
  • model_not_found … No policy-allowed peer currently serves modelNo seller your routing policy allows serves that model right now. Run the model test again and pick another OK model.
  • HTTP 400: Stream must be set to trueThe model is served only over the streaming Responses protocol, and a non-streaming Hermes call hit it. Use main and helper models that passed the non-streaming test.
  • 402 / insufficient_depositsNot enough funds. On a gateway, add funds to the workspace wallet in the console (Wallet & Funding: card or USDC). With a local buyer, antseed buyer balance shows Available vs Reserved; add funds with antseed buyer deposit (USDC on Base) or by card in the desktop app.
  • 401 from the gatewayThe key is missing, wrong, revoked or expired. Check hermes config get ANTSEED_API_KEY against the Keys page in the console, set it again, then /restart. For a gateway on this computer, antseed gateway key create --label hermes makes a new key.
  • curl: (7) Failed to connect to localhost:8379The gateway on this computer isn't running. antseed gateway service status shows whether the service is installed and answering; antseed gateway service install starts it again. Don't run antseed gateway start from Hermes' terminal tool: it stops when the session ends.
  • 429 / free_tier_exhaustedThe free sellers for that model are busy. Try another model, or try again in a few minutes.
  • Unknown provider 'antseed'The provider block is missing or misspelled. Check hermes config get providers.antseed and rerun the hermes config set providers.antseed.* commands.
  • Hermes still answers with the old modelThe gateway has not reloaded. Send /restart in your Hermes chat or run hermes gateway restart.
  • A model id with a dot ends up as nested keys in config.yamlhermes config set splits key paths on dots, so never put a model id in a key path (providers.antseed.models.kimi-k2.6…). The models: mapping is optional; model ids are fine as values (hermes config set model.default kimi-k2.6).
  • Hermes runs on a remote host and can't reach 127.0.0.1:8377The local buyer proxy only listens on localhost. Use a gateway: a server gateway, or a tunnel (antseed tunnel start), with its /v1 URL and a gateway key. Do not expose port 8377 directly.

Reference

Links

Hermes Agent (Nous Research)Hermes AI-provider docsAntseed skill: hermes-antseed (the steps above, written for your Hermes agent to follow)Antseed Agents guideAntseed gateway APIAntseed tunnels

Same category

Related

OpenClawAll integrations

Run Hermes on the open market

Run a gateway, point this tool at it, and pay per request.

Run a gatewayBecome a provider

All integrationsGateway API