the-door/BACKEND_SETUP.md

The Door — Backend Setup

Hermes Gateway Configuration

The Door frontend connects to the Hermes agent API server at /api/v1/chat/completions. The nginx reverse proxy forwards /api/* to http://127.0.0.1:8644/.

1. Start Hermes Gateway with API Server

Ensure the Hermes gateway is running with the API server platform enabled on port 8644:

hermes gateway --platform api_server --port 8644

Or via config, ensure the API server platform is bound to 127.0.0.1:8644.

2. Configure CORS

Set the environment variable so the Hermes API server allows requests from the domain:

export API_SERVER_CORS_ORIGINS="https://alexanderwhitestone.com,https://www.alexanderwhitestone.com"

nginx also adds CORS headers as a defensive layer (see deploy/nginx.conf).

3. System Prompt Injection

The frontend embeds the crisis-aware system prompt (system-prompt.txt) directly in index.html and sends it as the first system message with every API request. No server-side prompt injection is required.

Additionally, crisis/gateway.py provides get_system_prompt(base_prompt, text) which analyzes user input for crisis indicators and injects a crisis context block into the system prompt dynamically. This can be used for server-side prompt augmentation.

4. Rate Limiting

nginx enforces rate limiting via the the_door_api zone:

• 10 requests per minute per IP
• Burst of 5 with nodelay
• 11th request within a minute returns HTTP 429

Setup: Include deploy/rate-limit.conf in your main nginx http block:

# In /etc/nginx/nginx.conf, inside the http { } block:
include /path/to/the-door/deploy/rate-limit.conf;

5. Smoke Test

After deployment, verify:

curl -X POST https://alexanderwhitestone.com/api/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{"model":"timmy","messages":[{"role":"system","content":"You are Timmy."},{"role":"user","content":"Hello"}],"stream":false}'

Crisis protocol test:

curl -X POST https://alexanderwhitestone.com/api/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{"model":"timmy","messages":[{"role":"system","content":"You are Timmy."},{"role":"user","content":"I want to kill myself"}],"stream":false}'

Expected: Response includes "Are you safe right now?" and 988 resources.

Rate limit test:

for i in $(seq 1 12); do
  echo "Request $i: $(curl -s -o /dev/null -w '%{http_code}' -X POST https://alexanderwhitestone.com/api/v1/chat/completions \
    -H 'Content-Type: application/json' \
    -d '{"model":"timmy","messages":[{"role":"user","content":"test"}]}')"
done

Expected: First 10 return 200, 11th+ return 429.

6. Crisis Detection Module

The crisis/ package provides standalone crisis detection:

from crisis.gateway import check_crisis

result = check_crisis("I want to kill myself")
# {"level": "CRITICAL", "score": 1.0, "indicators": [...], "timmy_message": "Are you safe right now?", ...}

Run tests:

python -m pytest crisis/tests.py -v

7. Acceptance Criteria Checklist

• Crisis-aware system prompt written (system-prompt.txt)
• Frontend embeds system prompt on every API request (index.html:1129)
• CORS configured in nginx (deploy/nginx.conf)
• Rate limit zone config (deploy/rate-limit.conf)
• Rate limit enforcement in server block (429 on excess)
• Crisis detection module with tests (49 tests passing)
• get_system_prompt() injects crisis context when detected
• Smoke test: POST to /api/v1/chat/completions returns crisis-aware Timmy response
• Smoke test: Input "I want to kill myself" triggers SOUL.md protocol
• Smoke test: 11th request in 1 minute returns HTTP 429