hermes-gateway-api

Files (3)

• SKILL.md
• studio-gateway-connection.md · references/
• websocket-jsonrpc-protocol.md · references/

SKILL.md (first lines)

# Hermes Gateway API Server

The Hermes Gateway can serve an **HTTP API server** on port 8642, which external tools (Hermes Studio, custom dashboards, CLI scripts, the ACP server) connect to for session management, chat, memory, skills, and config.

This API server is **opt-in** — it does not start by default, even when the gateway is running. It requires explicit configuration.

## Prerequisites

- Hermes Agent v0.18.0+ (the `API_SERVER_KEY` security check was added in v0.18.x)
- `hermes gateway run` already works (the gateway process starts for messaging platforms)

## Enabling the API Server

### 1. Enable the API server

Add to `~/.hermes/.env`:

```ini
API_SERVER_ENABLED=true
```

### 2. Set a secure API key

**Required.** The gateway v0.18.x refuses to start the API server without a key, even for loopback-only binds on `127.0.0.1`. The key must be:

- **At least 16 characters** — shorter keys are rejected with: `API_SERVER_KEY is a placeholder or too short (<16 chars)`
- **Not a placeholder** — `dev-key`, `test`, `secret`, etc. are rejected
- **Cryptographically random** — use `openssl rand -hex 16` or similar

```bash
# Generate a secure key
openssl rand -hex 16

# Add to ~/.hermes/.env
API_SERVER_KEY=28582603a4559f46346896b9741de429
```

### 3. Match the key in your client

Any tool connecting to the API server must send `Authorization: Bearer <API_SERVER_KEY>` as an HTTP header.

For **Hermes Studio**, add to the Studio's `.env`:

```ini
HERMES_API_TOKEN=28582603a4559f46346896b9741de429
```

### 4. Restart the gateway

```bash
hermes gateway run --replace
```

## Verification

Check the gateway is listening and the API server is healthy:

```bash
# Port should be listening
lsof -i :8642

# Health endpoint
curl http://localhost:8642/health

# Should return: {"status": "ok", "platform": "hermes-agent", "version": "0.18.2"}
```

## Common Errors

### `ECONNREFUSED 127.0.0.1:8642`

The gateway is running but the API server is not enabled. Check:

1. `API_SERVER_ENABLED=true` is set in `~/.hermes/.env`
2. `API_SERVER_KEY=<32-char-hex>` is set (≥16 chars, not a placeholder)
3. Gateway was restarted after adding these variables

### `API_SERVER_KEY is required for the API server`

The API server is enabled but no key was provided. Generate a key and add it to `.env`.

### `API_SERVER_KEY is a placeholder or too short (<16 chars)`

The key exists but is too short or guessable. Generate a proper key with `openssl rand -hex 16`.

### `Gateway connection refused / 401 Unauthorized`
The client's bearer token doesn't match the server's `API_SERVER_KEY`. Verify:

```bash
# Check the server's expected key
grep API_SERVER_KEY ~/.hermes/.env

# Check the client's token
grep HERMES_API_TOKEN /path/to/client/.env
```

### `Cannot read properties of undefined (reading 'slice')` (500 on `/api/history`)

The Studio connected but the API response format doesn't match. Hermes Gateway v0.18.x returns OpenAI-compatible list format (`{ object, data, limit, offset, has_more }`), but Studio expects `{ items, total }`.

**Fix:** Patch `listSessions()` and `getMessages()` in `src/server/hermes-api.ts` to handle both:

```typescript
return resp.data ?? resp.items ?? []
```

See `references/studio-gateway-connection.md` for full steps.

### `API server rejected invalid API key` (from Studio, using correct .env)

The Studio's `.env` has the right token, but there are two separate places in `vite.config.ts` where the token is needed:

**1. Vite SSR env gap** — `loadEnv` does NOT set `process.env` by default. The Studio's SSR code (in `src/server/gateway-capabilities.ts`) reads `process.env.HERMES_API_TOKEN` at import time — if it's not in the shell environment, the token is empty.

**Fix** — In `vite.config.ts`, forward loaded env vars to `process.env` right after `loadEnv`:

```typescript
const env = loadEnv(mode, process.cwd(), '')
// Forward env vars to process.env so SSR code can read them

From mattdanielmurphy/ai-os, MIT.

More from mattdanielmurphy/ai-os