# 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

1. **Configure the service** (`config.yaml`):
   ```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"
   ```

2. **Start the Hermes service**:
   ```bash
   python main.py
   # Service will listen on 127.0.0.1:9120
   ```

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

4. **Test the deployment**:
   ```bash
   # 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.