steward_mirror/CONFIGURATION.md

# Configuration Guide

Steward uses a flexible configuration system that supports multiple sources:

1. **YAML Config File** (via `CONFIG_FILE` env var)
2. **Environment Variables** (via `STEWARD__SECTION__KEY` format)
3. **Default Values** (embedded in the schema)

Configuration is loaded in order of precedence, with environment variables overriding config file values, which override defaults.

## Quick Start

### Minimal Setup (Environment Variables Only)

Set these required environment variables:

```bash
export TELEGRAM_BOT_TOKEN="your-token-here"
export STEWARD__OPENAI__API_KEY="your-api-key-here"
```

Then run:
```bash
steward
```

### With YAML Config File

Create a config file (e.g., `config.yaml`):

```yaml
telegram:
  allowed_user_ids:
    - 1234567890
  group_ids:
    - -1005308306472

openai:
  model: "gpt-4-turbo"
  base_url: "https://api.openai.com/v1"

analysis:
  cron_hour: 9
  cron_minute: 30
```

Then run with:
```bash
CONFIG_FILE=config.yaml STEWARD__TELEGRAM__BOT_TOKEN="..." STEWARD__OPENAI__API_KEY="..." steward
```

### Docker / Kubernetes Setup

**In docker-compose.yml:**
```yaml
services:
  steward:
    image: ghcr.io/djw4/steward:latest
    environment:
      CONFIG_FILE: /etc/steward/config.yaml
      STEWARD__TELEGRAM__BOT_TOKEN: "${TELEGRAM_BOT_TOKEN}"
      STEWARD__OPENAI__API_KEY: "${OPENAI_API_KEY}"
    volumes:
      - ./config.yaml:/etc/steward/config.yaml:ro
      - ./data:/data
```

**In Kubernetes:**
```yaml
apiVersion: v1
kind: ConfigMap
metadata:
  name: steward-config
data:
  config.yaml: |
    telegram:
      allowed_user_ids:
        - 1234567890
      group_ids:
        - -1005308306472
    openai:
      model: "gpt-4o"

---
apiVersion: v1
kind: Secret
metadata:
  name: steward-secrets
type: Opaque
stringData:
  telegram-bot-token: "your-token"
  openai-api-key: "your-key"

---
apiVersion: apps/v1
kind: Deployment
metadata:
  name: steward
spec:
  template:
    spec:
      containers:
      - name: steward
        image: ghcr.io/djw4/steward:latest
        env:
        - name: CONFIG_FILE
          value: /etc/steward/config.yaml
        - name: STEWARD__TELEGRAM__BOT_TOKEN
          valueFrom:
            secretKeyRef:
              name: steward-secrets
              key: telegram-bot-token
        - name: STEWARD__OPENAI__API_KEY
          valueFrom:
            secretKeyRef:
              name: steward-secrets
              key: openai-api-key
        volumeMounts:
        - name: config
          mountPath: /etc/steward
        - name: data
          mountPath: /data
      volumes:
      - name: config
        configMap:
          name: steward-config
      - name: data
        emptyDir: {}
```

## Configuration Reference

### Telegram Section

```yaml
telegram:
  bot_token: ""                    # REQUIRED - set via STEWARD__TELEGRAM__BOT_TOKEN
  allowed_user_ids: []             # DM access list (empty = all users)
  group_ids: []                    # Group/channel access list (empty = all groups)
```

**Environment Variables:**
- `STEWARD__TELEGRAM__BOT_TOKEN` - Telegram bot token (REQUIRED)
- `STEWARD__TELEGRAM__ALLOWED_USER_IDS` - Comma-separated or JSON list: `123,456,789`
- `STEWARD__TELEGRAM__GROUP_IDS` - Comma-separated or JSON list: `-1005308306472`

### OpenAI Section

```yaml
openai:
  api_key: ""                      # REQUIRED - set via STEWARD__OPENAI__API_KEY
  base_url: "https://api.openai.com/v1"
  model: "gpt-4o"
  system_prompt: "..."             # Custom system prompt
```

**Environment Variables:**
- `STEWARD__OPENAI__API_KEY` - OpenAI API key (REQUIRED)
- `STEWARD__OPENAI__BASE_URL` - API endpoint URL
- `STEWARD__OPENAI__MODEL` - Model name
- `STEWARD__OPENAI__SYSTEM_PROMPT` - System prompt

### Analysis Section

```yaml
analysis:
  target_url: ""                   # Optional: API endpoint for analysis
  target_api_key: ""               # Optional: set via env var
  cron_hour: 8
  cron_minute: 0
```

**Environment Variables:**
- `STEWARD__ANALYSIS__TARGET_URL`
- `STEWARD__ANALYSIS__TARGET_API_KEY`
- `STEWARD__ANALYSIS__CRON_HOUR`
- `STEWARD__ANALYSIS__CRON_MINUTE`

### Memory Section

```yaml
memory:
  thread_memory_path: "thread_memory.json"  # Path to memory store
```

**Environment Variables:**
- `STEWARD__MEMORY__THREAD_MEMORY_PATH`
- `THREAD_MEMORY_PATH` (legacy)

### Tools Section

```yaml
tools:
  mcp_server_url: ""               # Optional: MCP/OpenAPI tool server
  mcp_server_api_key: ""           # Optional: set via env var
```

**Environment Variables:**
- `STEWARD__TOOLS__MCP_SERVER_URL`
- `STEWARD__TOOLS__MCP_SERVER_API_KEY`

### Matrix Section

```yaml
matrix:
  homeserver_url: ""               # Homeserver client-server base URL (e.g. http://matrix:8008)
  homeserver_domain: ""            # Homeserver server_name (e.g. matrix.aridgwayweb.com)
  as_token: ""                     # Appservice token (authenticates to the homeserver)
  hs_token: ""                     # Homeserver token (authenticates incoming transactions)
  bot_localpart: "steward"         # Bot user localpart -> @steward:<domain>
  appservice_id: "steward"         # Unique appservice ID
  listen_host: "0.0.0.0"           # Appservice HTTP server host
  listen_port: 8000                # Appservice HTTP server port
  allowed_room_ids: []             # Room allow-list (empty = all rooms)
  allowed_user_ids: []             # User MXID allow-list (empty = all users)
```

**Environment Variables:**
- `STEWARD__MATRIX__HOMESERVER_URL`
- `STEWARD__MATRIX__HOMESERVER_DOMAIN`
- `STEWARD__MATRIX__AS_TOKEN`
- `STEWARD__MATRIX__HS_TOKEN`
- `STEWARD__MATRIX__BOT_LOCALPART`
- `STEWARD__MATRIX__APPSERVICE_ID`
- `STEWARD__MATRIX__LISTEN_HOST`
- `STEWARD__MATRIX__LISTEN_PORT`
- `STEWARD__MATRIX__ALLOWED_ROOM_IDS` - Comma-separated list of room IDs
- `STEWARD__MATRIX__ALLOWED_USER_IDS` - Comma-separated list of user MXIDs

The Matrix bot is enabled when `homeserver_url`, `as_token`, and `hs_token` are all set. See [`matrix/steward_appservice.yaml`](matrix/steward_appservice.yaml) for the Synapse appservice registration template.

## Environment Variable Format

Environment variables follow the pattern: `STEWARD__SECTION__KEY=value`

Examples:
```bash
STEWARD__TELEGRAM__BOT_TOKEN="token123"
STEWARD__OPENAI__API_KEY="sk-..."
STEWARD__OPENAI__MODEL="gpt-4-turbo"
STEWARD__ANALYSIS__CRON_HOUR="9"
```

For list values, use comma-separated integers. JSON lists are also accepted for compatibility:
```bash
STEWARD__TELEGRAM__ALLOWED_USER_IDS=123456789,987654321
STEWARD__TELEGRAM__GROUP_IDS=-1005308306472
```

## Best Practices

### Security
- **Never** put secrets in YAML config files
- Always use environment variables for:
  - `STEWARD__TELEGRAM__BOT_TOKEN`
  - `STEWARD__OPENAI__API_KEY`
  - `STEWARD__ANALYSIS__TARGET_API_KEY`
  - `STEWARD__TOOLS__MCP_SERVER_API_KEY`

### Kubernetes
- Use `Secret` resources for sensitive data
- Use `ConfigMap` for non-sensitive configuration
- Mount both as environment variables for maximum flexibility

### Docker
- Use `.env` file for local development
- Use environment variables in production
- Mount ConfigMap volumes for complex configurations

## Backward Compatibility

The new configuration system is backward compatible with the old `pydantic-settings` approach:

- The `.env` file is no longer used by default (use `CONFIG_FILE` instead)
- Legacy environment variable names like `TELEGRAM_BOT_TOKEN` still work
- Properties on the `Settings` object work as before (e.g., `settings.telegram_bot_token`)

To migrate from `.env`:
1. Create a `config.yaml` with your configuration
2. Set `CONFIG_FILE` environment variable
3. Set secrets via `STEWARD__*` environment variables

### Setting up GitHub MCP

Configure the GitHub MCP server in `mcp.json` using `mcp-remote` to connect to the remote server:

```json
"github": {
  "command": "npx",
  "args": ["mcp-remote", "https://api.githubcopilot.com/mcp/", "--header", "Authorization: Bearer YOUR_GITHUB_PAT"]
}
```

Replace `YOUR_GITHUB_PAT` with your GitHub Personal Access Token from https://github.com/settings/personal-access-tokens/new

**Available GitHub Tools via MCP:**
- Repository management (list, create, read files, branches, commits)
- Issues and pull requests (create, update, comment, search)
- GitHub Actions workflows
- Code security and scanning
- And many more - see https://github.com/github/github-mcp-server for full docs