Configuration Guide
Ratelord is driven by environment variables for runtime tuning and a declarative policy file (`policy.yaml` or `.json`) that captures providers, pools, and enforcement rules.
Environment Variables
Use these variables to control networking, storage, policy paths, and clustering behaviour.
| Variable | Description | Default |
|---|---|---|
| RATELORD_PORT | HTTP port the daemon listens on. | 8090 |
| RATELORD_DB_PATH | Path to SQLite database file (state store). | ./ratelord.db |
| RATELORD_LOG_LEVEL | Logging verbosity (debug, info, warn, error). | info |
| RATELORD_POLICY_PATH | Policy file path (.json or .yaml). | ./policy.json |
| RATELORD_TLS_CERT | TLS certificate file path for HTTPS. | (disabled) |
| RATELORD_TLS_KEY | TLS private key file path. | (disabled) |
| RATELORD_REDIS_URL | Redis connection string for distributed mode. | (disabled) |
| RATELORD_WEB_DIR | Directory containing the Web UI assets. | (none) |
| RATELORD_MODE | Operating mode: leader, follower, or standalone. | leader |
| RATELORD_LEADER_URL | Leader node URL (followers only). | http://localhost:8090 |
| RATELORD_FOLLOWER_ID | Unique follower ID when in follower mode. | hostname |
| RATELORD_ADVERTISED_URL | Public URL this node broadcasts. | http://localhost:{port} |
| RATELORD_ARCHIVE_ENABLED | Enable cold storage archiving of events. | false |
| RATELORD_ARCHIVE_RETENTION | Retention before archiving. | 720h |
| RATELORD_BLOB_PATH | Filesystem path for blob storage. | ./blobs |
Policy Configuration
The policy file defines providers, pools, and codifies enforcement rules. Run the daemon with `ratelord-d --policy policy.yaml` to load a custom policy.
The document has four primary sections: providers, policies, optional pricing, and optional retention rules.
policies:
- id: "github-core-hard-limit"
scope: "global"
type: "hard"
limit: 5000
rules:
- name: "deny-exceeded-limit"
condition: "remaining < 0"
action: "deny"
params:
reason: "hard limit exceeded for GitHub core requests"
providers:
github:
- id: "github-main"
token_env_var: "GITHUB_TOKEN"Provider Configuration
Providers describe how the daemon fetches usage data from third parties. Each provider type (GitHub, OpenAI, etc.) defines connection details and credentials.
GitHub
Tracks core, search, and GraphQL rate limits. Use a Personal Access Token stored in an environment variable.
providers:
github:
- id: "my-org-github"
token_env_var: "GITHUB_TOKEN"
enterprise_url: "https://github.example.com/api/v3"OpenAI
Monitors RPM/TPM quotas and allows custom base URLs for Azure or proxying.
providers:
openai:
- id: "openai-prod"
api_key_env_var: "OPENAI_API_KEY"
org_id: "org-12345"
base_url: "https://api.openai.com"`api_key_env_var` supplies the API key, `org_id` enables organization-level tracking, and `base_url` can point to custom Azure endpoints or local proxies.