# API Server Port Troubleshooting

## Problem
API server binds to port 8642 (default) instead of 18789, or refuses to start on 0.0.0.0.

## Root Causes

### 1. Port mismatch (8642 vs 18789)
The API server reads its port from `API_SERVER_PORT` env var. Default is 8642.
If `.env` has `API_SERVER_HOST` and `API_SERVER_KEY` but no `API_SERVER_PORT`, it binds to 8642.

**Fix:**
```bash
echo 'API_SERVER_PORT=18789' >> ~/.hermes/.env
hermes gateway restart
```

Also add the `api_server` section to `config.yaml` (env vars alone may not be enough):
```yaml
api_server:
  enabled: true
  bind_address: 0.0.0.0
  port: 18789
  key: <your-key>
```

### 2. Binding to 0.0.0.0 without API key
Error: "binding to 0.0.0.0 requires API_SERVER_KEY"

**Fix (option A — set a key):**
```bash
echo 'API_SERVER_KEY=<your-random-key>' >> ~/.hermes/.env
```

**Fix (option B — localhost only, no key needed):**
```bash
echo 'API_SERVER_HOST=127.0.0.1' >> ~/.hermes/.env
```

### 3. Config section missing
`.env` variables are read but `config.yaml` may lack the `api_server` section entirely.
Check: `grep -A10 api_server ~/.hermes/config.yaml` — if nothing returns, add the section.

## Verification
```bash
curl http://<ip>:<port>/health
# Expected: {"status": "ok", "platform": "hermes-agent"}
```

Check actual port in logs:
```bash
grep "listening on" ~/.hermes/logs/gateway.log | tail -1
```