# Configuration

All configuration is done through environment variables. Copy `.env.example` to `.env` and set the values before starting the server.

```bash
cp .env.example .env
```

---

## Gitea Settings

| Variable | Required | Default | Description |
|---|---|---|---|
| `GITEA_URL` | Yes | — | Base URL of your Gitea instance (e.g. `https://gitea.example.com`) |
| `GITEA_TOKEN` | Yes | — | API token of the Gitea bot user |

The `GITEA_TOKEN` must be a token belonging to a user that has at least read access to all repositories you want the AI to access. The server validates the token on startup by calling the Gitea `/api/v1/user` endpoint.

---

## MCP Server Settings

| Variable | Required | Default | Description |
|---|---|---|---|
| `MCP_HOST` | No | `127.0.0.1` | Interface to bind to |
| `MCP_PORT` | No | `8080` | Port to listen on |
| `MCP_DOMAIN` | No | — | Public domain name (used for Traefik labels in Docker) |
| `LOG_LEVEL` | No | `INFO` | Log level: `DEBUG`, `INFO`, `WARNING`, `ERROR`, `CRITICAL` |
| `STARTUP_VALIDATE_GITEA` | No | `true` | Validate Gitea token and connectivity at startup via `/api/v1/user` |

If startup validation fails with `403 Forbidden`, the token is authenticated but lacks permission to access `/api/v1/user`. Grant the bot user token the required API scope/permissions, or temporarily set `STARTUP_VALIDATE_GITEA=false` in controlled troubleshooting environments.

---

## Authentication Settings

| Variable | Required | Default | Description |
|---|---|---|---|
| `AUTH_ENABLED` | No | `true` | Enable or disable API key authentication |
| `MCP_API_KEYS` | Yes (if auth enabled) | — | Comma-separated list of valid API keys |
| `MAX_AUTH_FAILURES` | No | `5` | Number of failed attempts before rate limiting an IP |
| `AUTH_FAILURE_WINDOW` | No | `300` | Time window in seconds for counting failures |

### API Key Requirements

- Minimum length: 32 characters
- Recommended: generate with `make generate-key` (produces 64-character hex keys)
- Multiple keys: separate with commas — useful during key rotation

```env
# Single key
MCP_API_KEYS=abc123...

# Multiple keys (grace period during rotation)
MCP_API_KEYS=newkey123...,oldkey456...
```

> **Warning:** Setting `AUTH_ENABLED=false` disables all authentication. Only do this in isolated development environments.

---

## File Access Settings

| Variable | Required | Default | Description |
|---|---|---|---|
| `MAX_FILE_SIZE_BYTES` | No | `1048576` | Maximum file size the server will return (bytes). Default: 1 MB |
| `REQUEST_TIMEOUT_SECONDS` | No | `30` | Timeout for upstream Gitea API calls (seconds) |

---

## Audit Logging Settings

| Variable | Required | Default | Description |
|---|---|---|---|
| `AUDIT_LOG_PATH` | No | `/var/log/aegis-mcp/audit.log` | Absolute path for the JSON audit log file |

The directory is created automatically if it does not exist (requires write permission).

---

## Full Example

```env
# Gitea
GITEA_URL=https://gitea.example.com
GITEA_TOKEN=abcdef1234567890abcdef1234567890

# Server
MCP_HOST=127.0.0.1
MCP_PORT=8080
MCP_DOMAIN=mcp.example.com
LOG_LEVEL=INFO
STARTUP_VALIDATE_GITEA=true

# Auth
AUTH_ENABLED=true
MCP_API_KEYS=a1b2c3d4e5f6...64chars
MAX_AUTH_FAILURES=5
AUTH_FAILURE_WINDOW=300

# Limits
MAX_FILE_SIZE_BYTES=1048576
REQUEST_TIMEOUT_SECONDS=30

# Audit
AUDIT_LOG_PATH=/var/log/aegis-mcp/audit.log
```