Skip to main content

​
What is Hermes Agent?

Hermes Agent (by Nous Research) is a CLI-first AI agent available as a one-click app in the Knotie VPS App Catalog — mirroring the OpenClaw integration but with a lighter-weight transport. For the high-level overview, feature comparison, and use cases, see Hermes Agent overview. This page is the deep-dive setup guide that walks through the SSH chat transport, the deploy pipeline, the chat API, and configuration. Key properties:
  • Runs on your customer’s VPS, routed through the Knotie AI Gateway (partner earns margin on every AI call)
  • No extra daemon or public port required — portal chat uses a secure SSH one-shot transport instead of nginx/TLS
  • AI Gateway key is automatically minted during deploy — no human ever enters an API key
  • Multi-turn memory preserved across chat sessions via Hermes’s built-in memories/ store and the --continue flag
  • Optional Telegram integration — wire a bot token during deploy to let customers chat via Telegram too
⚠️ Hermes Agent is currently in beta / catalog-deploy-only mode. Stage-1 reinstall from the VPS catalog is guarded; use the catalog deploy flow described below.

​
How portal chat works

Browser
  → Partner Portal  POST /api/whitelabel/vps/instances/:id/hermes-agent/chat  (cookie auth)
  → SSH into VPS
  → hermes -z "<prompt>" --continue           (one-shot, resume last session)
  → stdout (reply text only)
  → JSON { reply, sessionId, model } back to browser
Compared to OpenClaw, there is no port 18790, no nginx layer, no knock header — Hermes has no built-in HTTP chat server, so the portal talks to it via SSH directly. This means:
  • ✅ Smaller attack surface (no new public port on the VPS)
  • ✅ Fewer moving parts (no daemon to manage)
  • ⚠️ Higher first-token latency (~5–40 s, no streaming) — the agent process starts fresh per request

​
Prerequisites

RequirementWhere to get it
Active VPS instancePartner Portal → VPS Servers → My Instances
Partner Portal accessRequired to trigger the catalog deploy
Telegram bot token (optional)Create a bot via @BotFather on Telegram
Telegram chat ID (optional)Use @userinfobot to look up the chat/group ID
No separate API key setup is needed — the platform mints a Knotie AI Gateway key automatically when you deploy.

​
Deploying Hermes Agent

​
Step 1 — Open the App Catalog on your VPS

  1. In the Partner Portal, go to VPS Servers → My Instances
  2. Find the VPS you want to deploy on and click its card
  3. Click App Catalog (or Reinstall)
  4. Select Hermes Agent from the catalog

​
Step 2 — Fill in the deploy form

The pre-deploy form collects:
FieldRequiredDescription
Customer / Business name✅ YesUsed as the agent’s display name and written into SOUL.md
Telegram bot tokenNoWire the agent to a Telegram bot for out-of-band messaging
Telegram chat IDNoRequired if you supply a bot token

​
Step 3 — Wait for deploy to complete

After you click Deploy, the platform:
  1. Mints a real Knotie AI Gateway key (sk-…) with the partner’s entitled models
  2. SSH-runs the two-stage deploy script on the VPS (returns 202 immediately; runs in background)
  3. The deploy script:
    • Installs Hermes CLI (v0.15.1+) via cloud-init
    • Wires Hermes’s custom OpenAI-compatible provider to https://api.knotie.ai/v1
    • Writes the AI key directly into config.yaml (under model.api_key) — not .env
    • Writes SOUL.md with the customer/business name
    • Best-effort registers the Knotie MCP server
    • Optionally wires Telegram if a bot token was supplied
    • Runs hermes doctor + a one-shot smoke test to verify the setup
    • Writes the /var/lib/hermes-agent/catalog-deploy-complete marker
  4. Updates the instance status: deploying:hermes-agent → hermes-agent
The VPS instance card in the portal shows the updated status once deploy completes. If the deploy is still running, the AI Chat button returns a 409 agent_not_ready — this clears once the marker is written.

​
Chatting with Hermes Agent

  1. In the customer’s whitelabel portal, go to AI Chat
  2. In the agent selector, choose ⚡ Hermes Agent
  3. Type a message and send
The first reply may take 5–40 seconds (Hermes starts fresh per request). Subsequent turns in the same browser session use --continue to resume the most recent Hermes conversation thread, so the agent remembers context.

​
Session behaviour

  • Each VPS instance is single-customer. All browser tabs for that customer share the same Hermes conversation thread — not cross-tenant.
  • To start a fresh conversation, have the customer reload the page or use a new browser session (a dedicated session-reset endpoint is a planned follow-up).

​
Chat API reference

The portal uses this internal route; you can also call it from custom integrations: 
POST /api/whitelabel/vps/instances/:instanceId/hermes-agent/chat
GET  /api/whitelabel/vps/instances/:instanceId/hermes-agent/chat  (health check)
Auth: Whitelabel session cookie (customer must be logged in to the partner portal). POST request body: 
{
  "message": "Hello, what can you help me with?",
  "sessionId": "optional-session-identifier"
}
Success response (200): 
{
  "reply": "Hi! I'm here to help. What would you like to work on?",
  "sessionId": "sess_abc123",
  "model": "knotie-provider/auto"
}
Error responses:
StatusCodeMeaning
401unauthorizedCustomer not authenticated
403forbiddenInstance belongs to a different customer
404instance_not_foundVPS instance not found
409agent_not_readyDeploy script hasn’t finished yet (marker not written)
422invalid_inputMessage body missing or empty
502agent_errorHermes returned an error or empty reply
503ssh_unavailableCould not SSH into the VPS
504agent_timeoutHermes took longer than ~55 s to reply

​
Telegram integration

If you supplied a Telegram bot token and chat ID during deploy, the install script registers the Hermes messaging gateway to forward messages from that Telegram conversation to the agent (and vice versa). This is separate from portal chat — both work in parallel:
  • Portal chat: browser → SSH → Hermes
  • Telegram chat: Telegram → Hermes messaging gateway (running as a systemd service)

​
Configuration reference

These values are written to ~/.hermes/config.yaml during deploy:
SettingValue set by deployDescription
model.providercustomUses the custom OpenAI-compatible provider
model.base_urlhttps://api.knotie.ai/v1Knotie AI Gateway endpoint
model.api_keyAuto-minted sk-… keyWritten directly into config (not .env) — required for Hermes 0.15.1+
model.defaultauto (or primary model)Resolves to the best available model
The AI key is stored on the VPS only — it is never persisted in the Knotie database.

​
Troubleshooting

Chat returns 409 agent_not_ready The deploy script hasn’t finished yet. Check whether the completion marker exists on the VPS: 
ls /var/lib/hermes-agent/catalog-deploy-complete
If missing, wait a few minutes and retry. If the deploy appears stalled, re-trigger from the portal (Reinstall → Hermes Agent). Agent replies with errors or blank responses Run the health check on the VPS: 
hermes doctor
If hermes doctor reports an auth error, the API key in config.yaml may be incorrect. Re-deploy from the catalog to re-mint and reinject the key. Verify the Knotie Gateway is wired correctly: 
grep -A5 'provider: custom' ~/.hermes/config.yaml
# Expected:
#   base_url: https://api.knotie.ai/v1
#   api_key: sk-...
First message times out (504) Hermes starts fresh on every request. A 504 means Hermes took more than ~55 s to respond. This can happen on an under-resourced VPS (a small entry-tier plan at peak load). Try: 
hermes -z "ping" --continue    # run a warm-up manually
If timeouts are chronic, consider upgrading the VPS plan. Portal chat shows ⚡ Hermes Agent but the channel status is stuck on “deploying” The channelReady flag is set optimistically once the instance shows installedAppId=hermes-agent. If the deploy hasn’t fully completed, the chat button may appear active but return 409. Use the health endpoint to confirm: 
curl -b <session-cookie> https://<partner-domain>/api/whitelabel/vps/instances/<id>/hermes-agent/chat
# Returns 200 with { status: "ok" } when ready
Support