> ## Documentation Index
> Fetch the complete documentation index at: https://cofounder.appeeky.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Hermes Agent (coding agent)

> Let the Co-founder hand feature-gap builds to your own Hermes Agent — it opens the PR.

The Co-founder is a strategist, not a code runner. When it spots a **feature gap** a competitor already ships — or a recurring, well-scoped build request in your reviews — it can package the task and trigger a run on **your own [Hermes Agent](https://hermes-agent.nousresearch.com/) gateway**. Hermes owns the sandbox, repo access, and pull-request lifecycle. Appeeky never executes code.

This is the `engineering_delegate` action with `provider: "hermes"`.

## 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)
```

Appeeky stores the returned `run_id` as the action's `external_id`, then reconciles status via `GET /v1/runs/{id}` (scheduled poller \~every 10 minutes, plus the next briefing and a manual refresh endpoint). **Execution still lives entirely on your gateway** — Appeeky never clones repos or runs code.

## Prerequisites

See **[Hosting a coding agent](./hosting-coding-agents)** for the full VPS + named Cloudflare Tunnel recipe. Short version:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
# ~/.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
```

Then start the gateway: `hermes gateway` (or a systemd unit). See the [Hermes API Server docs](https://hermes-agent.nousresearch.com/docs/user-guide/features/api-server).

## Reachability & security (you host the gateway)

Appeeky is the strategist; **you host the coding agent**. Appeeky's servers make outbound requests to the `baseUrl` you provide, so the gateway must be reachable from the internet and locked down:

* **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](./hosting-coding-agents).
* **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

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
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"
    }
  }'
```

Before saving, Appeeky calls `GET /v1/capabilities` on your gateway with the bearer token to verify it is reachable and the key is valid.

| Field     | Where       | Required | Notes                                                     |
| --------- | ----------- | -------- | --------------------------------------------------------- |
| `apiKey`  | credentials | ✅        | Your gateway's `API_SERVER_KEY`                           |
| `baseUrl` | config      | ✅        | Full URL incl. port, e.g. `https://host:8642`             |
| `deliver` | config      | —        | Channel Hermes reports back to (e.g. `slack`, `telegram`) |

## Enable

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
PUT /v1/cofounder/preferences
{ "enabledIntegrations": ["hermes"] }
```

(Connecting via the dashboard does this automatically.)

## What Appeeky sends

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
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."
}
```

The brief always ends with **draft-PR-by-default guardrails** so nothing merges or deploys without you.

## 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

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
DELETE /v1/cofounder/integrations/hermes
```