Hermes Agent (coding agent)

​

How it works

Co-founder run
  → ASO / Product agents detect a feature gap + evidence
  → reasoner emits an `engineering_delegate` action (provider: hermes)
  → you approve it (delegations always require explicit approval)
  → Appeeky POSTs to your Hermes gateway: POST /v1/runs
  → Hermes clones, branches, codes, tests, opens a draft PR
  → Hermes delivers a summary to your channel (optional)

​

Prerequisites

# ~/.hermes/.env
API_SERVER_ENABLED=true
API_SERVER_KEY=$(openssl rand -hex 32)
API_SERVER_PORT=8642
API_SERVER_HOST=127.0.0.1   # prefer tunnel/proxy in front; don't expose raw

​

Reachability & security (you host the gateway)

• Public HTTPS required in production. In production, baseUrl must be an https:// URL. Plain http:// is rejected.
• Private addresses are blocked. For SSRF safety, Appeeky refuses gateway URLs that resolve to loopback (127.0.0.1, localhost), private ranges (10.x, 172.16–31.x, 192.168.x), link-local / cloud-metadata (169.254.169.254), or other reserved addresses. Point baseUrl at a genuinely public host.
• Use a durable hostname. Quick tunnels (*.trycloudflare.com) change on every restart and will break Integrations. Prefer a named Cloudflare Tunnel on your domain (hermes.yourdomain.com) or a VPS + reverse proxy. Details in Hosting a coding agent.
• Keep the key strong & rotate it. API_SERVER_KEY is the only credential guarding your gateway — use openssl rand -hex 32 and rotate if leaked. Appeeky stores it encrypted at rest and never returns it to the client.

Local development only: when Appeeky runs in dev (NODE_ENV != production), http://127.0.0.1:8642 is allowed so you can test against a laptop gateway. This never applies to the hosted product.

​

Setup

curl -X PUT https://api.appeeky.com/v1/cofounder/integrations/hermes \
  -H "X-API-Key: $APPEEKY_KEY" \
  -d '{
    "credentials": { "apiKey": "<API_SERVER_KEY>" },
    "integrationConfig": {
      "baseUrl": "https://your-host:8642",
      "deliver": "slack"
    }
  }'

​

Enable

PUT /v1/cofounder/preferences
{ "enabledIntegrations": ["hermes"] }

​

What Appeeky sends

POST https://your-host:8642/v1/runs
Authorization: Bearer <API_SERVER_KEY>
X-Hermes-Session-Key: appeeky:<appId>:<task-slug>

{
  "input": "# Engineering task from App Co-founder\n## <title>\n**Feature gap:** …\n**Why now (evidence):** …\n**Target repo:** owner/repo\n## Task\n<brief>\n## Guardrails (hard)\n- Open a draft pull request — do NOT merge or deploy.\n- Run the project's test/lint suite before opening the PR.",
  "session_id": "appeeky:<appId>:<task-slug>",
  "instructions": "You are an engineering agent executing a task handed off by the App Co-founder. Work in the repository owner/repo. When finished, deliver a summary to slack."
}

​

Safety model

• No Appeeky secrets leave Appeeky. Your GitHub token / repo access lives on the Hermes side. Appeeky only sends the task brief.
• Always approval-gated. engineering_delegate never auto-runs by autopilot level — it waits for your approval in chat or the Actions queue. (You can opt a delegation type into auto-approval explicitly via autoApproveTypes, but that’s off by default.)
• Rate-limited. Appeeky caps applied delegations (default: 10/day and 3 in-flight per owner) so a runaway loop cannot flood your gateway.
• Read mode blocks it. In agentMode: read, the Co-founder will not propose delegations at all.
• Traceable. Every run carries session_id = appeeky:<appId>:<task-slug>.

​

Disable

DELETE /v1/cofounder/integrations/hermes