Hermes Service - Nginx Deployment with Security Features

Overview

This service provides a multi-user Hermes Agent API that can be deployed behind Nginx with IP address filtering and API key authentication capabilities.

Configuration

The service uses a config.yaml file for configuration. Key security features include:

IP Address Checking

Enable with security.enable_ip_check: true
Configure allowed IPs in security.allowed_ips (supports CIDR notation)
Works with X-Forwarded-For header when behind Nginx

API Key Authentication

Enable with security.enable_api_key: true
Choose authentication method: header (custom header) or bearer (Authorization header)
For bearer method, use Authorization: Bearer <apikey> header
For header method, configure custom header name via security.api_key_header
Define valid API keys in security.api_keys

Nginx Integration

Real IP detection from X-Forwarded-For header
Trusted proxy configuration
Service binds to localhost by default for security

Deployment with Nginx

Configure the service (config.yaml):

security:
  enable_ip_check: true
  allowed_ips:
    - "192.168.1.0/24"
    - "203.0.113.0/24"
  enable_api_key: true
  api_keys:
    - key: "your-secret-api-key"
      description: "Production API key"

Start the Hermes service:

python main.py
# Service will listen on 127.0.0.1:9120

Configure Nginx (see nginx.conf.example):
- Set up reverse proxy to localhost:9120
- Configure SSL (recommended)
- Optional: Add additional IP restrictions at Nginx level

Test the deployment:

# Health check (no auth required)
curl http://your-domain.com/health

# API call with API key
curl -H "X-API-Key: your-secret-api-key" \
     -X POST http://your-domain.com/api/v1/sessions \
     -d '{"user_id": "test"}'

Security Best Practices

Always run behind Nginx or similar reverse proxy in production
Use HTTPS/SSL for all communications
Regularly rotate API keys
Restrict allowed IPs to known client networks
Monitor access logs for suspicious activity

Configuration Reference

See config.yaml for complete configuration options and examples.

2.3 KiB Raw Blame History