Configuration

Logchef uses a minimal TOML configuration file for bootstrap settings, with runtime configuration managed through the Admin Settings UI. This guide explains the essential configuration options and how to manage non-essential settings through the web interface.

Configuration Architecture

Logchef separates configuration into two categories:

Essential (Bootstrap) Settings - Required in config.toml:

• Server connection details (port, host)
• SQLite database path
• OIDC authentication credentials
• Admin user emails and API token secrets
• Logging configuration

Runtime Settings - Managed via Admin Settings UI:

• Alerting configuration (SMTP settings, intervals, timeouts)
• AI/LLM settings (API keys, models, endpoints)
• Session management (duration, concurrency)
• Frontend URL for CORS

On first boot, Logchef seeds the database with values from config.toml. After that, runtime settings are stored in the database and managed through the Admin Settings UI at Administration → System Settings.

Essential Configuration

These settings must be present in config.toml for Logchef to start:

Server Settings

Configure the HTTP server and frontend settings:

[server]
# Port for the HTTP server (default: 8125)
port = 8125

# Host address to bind to (default: "0.0.0.0")
host = "0.0.0.0"

# URL of the frontend application
# Leave empty in production, used only in development
frontend_url = ""

# HTTP server timeout for requests (default: 30s)
http_server_timeout = "30s"

# Trusted reverse-proxy IPs/CIDRs for client-IP resolution. Empty (default)
# trusts no proxy — the client IP is the direct connection peer. Set to your
# reverse proxy's address(es) to resolve the real client from proxy_header.
trusted_proxies = []
# Forwarding header read for the client IP, ONLY when the direct peer is one of
# trusted_proxies (otherwise ignored, so untrusted callers can't spoof it).
proxy_header = "X-Forwarded-For"

Client IP behind a proxy

trusted_proxies is what lets client-IP features (e.g. per-IP rate limiting) work behind a reverse proxy. List only your proxy’s own address(es), and make sure that proxy overwrites the forwarding header rather than appending a client-supplied one — otherwise the client IP can be spoofed. Invalid entries or a 0.0.0.0/0 wildcard fail startup.

Database Configuration

SQLite database settings for storing metadata:

[sqlite]
# Path to the SQLite database file
path = "logchef.db"

Authentication

OpenID Connect (OIDC)

Configure your SSO provider (example using Dex):

[oidc]
# URL of your OIDC provider
provider_url = "http://dex:5556/dex"

# Authentication endpoint URL (Optional: often discovered via provider_url)
auth_url = "http://dex:5556/dex/auth"

# Token endpoint URL (Optional: often discovered via provider_url)
token_url = "http://dex:5556/dex/token"

# OIDC client credentials
client_id = "logchef"
client_secret = "logchef-secret"

# CLI client ID for CLI authentication (public OIDC client, PKCE flow)
cli_client_id = "logchef-cli"

# Callback URL for OIDC authentication
# Must match the URL configured in your OIDC provider
redirect_url = "http://localhost:8125/api/v1/auth/callback"

# Required OIDC scopes
scopes = ["openid", "email", "profile"]

# Keep false unless your OIDC provider omits email_verified while verifying
# email addresses by other means. Missing/null email_verified is allowed only
# when this is true; explicit email_verified=false is always rejected.
skip_email_verified_check = false

If you plan to use the CLI, create a public OIDC client with loopback redirect URIs (http://127.0.0.1:19876/callback through http://127.0.0.1:19878/callback) and set oidc.cli_client_id to that client ID.

oidc.skip_email_verified_check is useful for providers such as Cloudflare Access that do not emit the email_verified claim. It does not bypass an explicit email_verified=false response.

Local authentication (run without OIDC)

Logchef can run without an external identity provider. Enable built-in email+password authentication and bootstrap an admin at startup:

[auth.local]
enabled = true
admin_email = "admin@example.com"
# Prefer the environment variable below over committing a password to a file.
# Minimum 10 characters. Stored as a bcrypt hash; the plaintext is never logged.
admin_password = "change-me-please"

Or via environment variables:

LOGCHEF_AUTH__LOCAL__ENABLED=true
LOGCHEF_AUTH__LOCAL__ADMIN_EMAIL=admin@example.com
LOGCHEF_AUTH__LOCAL__ADMIN_PASSWORD=change-me-please

When local auth is enabled the whole [oidc] section becomes optional. The login page shows an email/password form (and the SSO button too, if OIDC is also configured). The bootstrap admin is created (or its password updated) on every startup, so rotating the password is just a config change + restart. The login endpoint is rate limited per IP and per email.

SSO auto-provisioning (JIT user creation)

By default, an OIDC login from a user who doesn’t already exist in Logchef is rejected with “user not found”: someone has to create the user first (via the admin UI or declarative provisioning). Auto-provisioning removes that step for your own company domain: a first-time OIDC login from an allowed email domain creates the user on the spot.

[auth.auto_provision]
# Off by default.
enabled = true
# Email domains eligible for auto-provisioning. Matching is an exact,
# case-insensitive comparison against the domain part of the OIDC email
# claim — no subdomain or wildcard matching. Required (non-empty) when enabled;
# startup fails otherwise.
allowed_domains = ["example.com"]
# Optional: team IDs the new user is added to, as role "member". Best-effort —
# a nonexistent team ID is logged and skipped, it never fails the login.
default_team_ids = [1]

Or via environment variables:

LOGCHEF_AUTH__AUTO_PROVISION__ENABLED=true
LOGCHEF_AUTH__AUTO_PROVISION__ALLOWED_DOMAINS="example.com"
LOGCHEF_AUTH__AUTO_PROVISION__DEFAULT_TEAM_IDS="1"

Behavior notes:

• Auto-provisioned users are always created as regular, active members, never admins. Admin access still comes only from auth.admin_emails.
• Provisioning runs after the email_verified claim check, so an unverified email can never mint a user.
• The created users are unmanaged with respect to declarative provisioning: the reconciler never adopts, updates, or prunes them, and admins can edit them freely.
• Applies to the browser OIDC login only. The CLI token exchange still requires the user to already exist. Run the web login once first.

Auth Settings

Configure authentication behavior:

[auth]
# List of email addresses that have admin privileges (required)
admin_emails = ["admin@corp.internal"]

# Secret key for API token hashing (required, min 32 characters)
# Generate with: openssl rand -hex 32
api_token_secret = "your-secret-key-minimum-32-characters-long"

Note: Session duration, concurrent session limits, and default token expiry are managed via the Admin Settings UI under Authentication settings.

Logging

Configure application logging:

[logging]
# Log level: "debug", "info", "warn", "error"
level = "info"

Query Settings

Control interactive query limits separately from streaming downloads.

[query]
# Browser Run defaults to small previews and caps large responses.
default_preview_limit = 1000
max_preview_limit = 100000
max_response_bytes = 67108864
default_timeout_seconds = 30
max_timeout_seconds = 120
max_concurrent_per_user = 3
max_concurrent_global = 30

[export]
# Download jobs use this separate, higher cap and keep completed artifacts briefly.
max_rows = 1000000
default_timeout_seconds = 120
max_timeout_seconds = 600
max_concurrent_per_user = 1
max_concurrent_global = 5
artifact_ttl = "24h"
formats = ["csv", "ndjson"]

[shares]
default_ttl = "720h"
max_query_text_bytes = 1048576

The UI uses preview limits for Run and export limits for Download.

Environment variables: LOGCHEF_QUERY__MAX_PREVIEW_LIMIT=100000, LOGCHEF_EXPORT__MAX_ROWS=1000000

Live tail settings

Controls the /logs/tail SSE streams that power the explorer’s Live toggle. ClickHouse sources are polled every poll_interval; VictoriaLogs sources stream natively. The other settings are admission guardrails shared by both backends.

[tail]
poll_interval = "2s"
max_per_user = 2
max_global = 20
# Kept under [server] http_server_timeout (15m default) — the write deadline
# caps any single response, tails included. Clients re-arm on end.
session_ttl = "14m"
max_rows_per_sec = 100

Environment variables: LOGCHEF_TAIL__MAX_PER_USER=4, LOGCHEF_TAIL__SESSION_TTL=20m

Rate limiting

Fixed-window request limits: per-IP (plus an optional global cap) on the unauthenticated auth/token endpoints, and per-user on the query endpoints. Off by default — enable it deliberately (see the proxy note below).

[rate_limit]
enabled = false
auth_per_ip_per_minute    = 20     # /auth/login, /auth/callback, /cli/token, ...
auth_global_per_minute    = 300    # 0 disables the global cap
query_per_user_per_minute = 120    # /logs/query, /logs/histogram, field values

Environment variables: LOGCHEF_RATE_LIMIT__ENABLED=true, LOGCHEF_RATE_LIMIT__AUTH_PER_IP_PER_MINUTE=30

Rejections return HTTP 429 and increment the logchef_rate_limit_rejections_total{scope} metric.

Public demo read-only mode

For an internet-facing showcase, Logchef can make its metadata control plane read-only while keeping authentication, source reads, LogchefQL/native queries, histograms, AI query generation, and live exploration available:

[demo]
read_only = true

Or set LOGCHEF_DEMO__READ_ONLY=true. The server advertises this mode through /api/v1/meta, so the web UI displays a persistent explanation and removes dashboard mutation controls. Blocked metadata writes return HTTP 403 with error_type: DEMO_INSTANCE.

For an intentional public demo, show_login_credentials = true lets Logchef expose the configured [auth.local] email and password through /api/v1/meta so the login page can display and prefill them at runtime. You can also set LOGCHEF_DEMO__SHOW_LOGIN_CREDENTIALS=true. This option is off by default. Enabling it publicly exposes the configured local authentication credentials to every visitor, so never enable it for a normal deployment or with credentials that must remain secret.

[demo]
read_only = true
show_login_credentials = true

Browser-only preferences such as theme, timezone, view mode, and the fields panel remain usable. They are saved to local storage instead of the shared demo account, so one visitor cannot change another visitor’s interface.

Successful queries still increment privacy-safe daily usage and latency aggregates. Raw query text and per-visitor history are neither retained nor returned, including from the admin activity view.

If an internal bootstrap job needs to refresh seeded demo resources after an upgrade, set LOGCHEF_DEMO__PROVISIONING_TOKEN and send the same secret in the X-Logchef-Demo-Provisioning-Token header. Keep this header private to the internal job; do not add it in a public reverse proxy.

This mode is intended for a shared public demo, not as a substitute for normal role-based access control. Keep datasource credentials read-only and retain reverse-proxy rate limits for public traffic.

Dashboard result cache

Dashboards auto-refresh every panel on an interval, so a dashboard with N panels open by M viewers can generate up to N×M backend queries per refresh cycle. A shared, server-side result cache collapses that into one backend hit per panel per TTL window: the first request fills the cache, and every other request in that window is served the stored result.

Caching is per dashboard: each dashboard’s TTL lives in its own settings (default 10m; 0 disables caching for that dashboard). Only dashboard panel requests are cached — explorer and other ad-hoc queries are never cached. The [dashboard_cache] section sets the server-wide switch and bounds.

[dashboard_cache]
# Master switch for the per-dashboard result cache.
enabled = true
# Default TTL applied when a dashboard does not set its own (client default mirror).
default_ttl = "10m"
# Hard clamp on any dashboard's requested TTL.
max_ttl = "1h"
# Total encoded bytes held across all cache entries (64 MiB).
max_bytes = 67108864
# Per-response cap; responses larger than this bypass the cache instead of being stored (4 MiB).
max_entry_bytes = 4194304
# Maximum number of cache entries.
max_entries = 1024
# Bounds concurrent distinct datasource fills. Worst-case in-flight buffering is
# max_concurrent_fills × max_entry_bytes.
max_concurrent_fills = 8

Environment variables: LOGCHEF_DASHBOARD_CACHE__ENABLED=false, LOGCHEF_DASHBOARD_CACHE__MAX_TTL=30m

Behind a reverse proxy

The per-IP limiter keys on the resolved client IP. Behind a reverse proxy, set server.trusted_proxies to the proxy’s exact IP or CIDR and ensure the proxy overwrites server.proxy_header (default X-Forwarded-For). Logchef ignores the forwarding header from untrusted peers, preventing callers from spoofing their address. Leave per-IP limiting off until trusted-proxy resolution is configured; the global auth cap and per-user query limit remain usable.

Runtime Configuration (Admin Settings UI)

The following settings are managed through the web interface at Administration → System Settings after first boot. You can optionally set initial values in config.toml which will be seeded to the database on first boot.

AI SQL Generation

Configure AI-powered SQL generation through the Admin Settings UI:

Settings available:

• Enabled: Enable/disable AI features
• Provider: AI transport to use — openai (default) or bedrock
• Region: AWS region for the bedrock provider (e.g. us-east-1); required when provider = "bedrock"
• API Key: OpenAI API key (marked as sensitive, hidden in UI); used by the openai provider
• Base URL: OpenAI-compatible API endpoint (default: https://api.openai.com/v1); used by the openai provider
• Model: Model name (e.g., “gpt-4o”, “gpt-4o-mini” for OpenAI; a Bedrock model id / inference-profile ARN such as “anthropic.claude-3-5-sonnet-20241022-v2:0” for Bedrock)
• Max Tokens: Maximum tokens to generate (default: 1024)
• Temperature: Generation temperature 0.0-1.0 (default: 0.1)

Supported Providers:

• OpenAI (provider = "openai"): Use default base URL (https://api.openai.com/v1)
• OpenRouter: OpenAI provider with base URL set to “https://openrouter.ai/api/v1”
• Azure OpenAI: OpenAI provider pointed at your Azure endpoint
• Local Models: OpenAI provider pointed at your local OpenAI-compatible server
• AWS Bedrock (provider = "bedrock"): Native Bedrock via the unified Converse API. Works across Claude/Llama/Titan/Nova/Mistral. Authenticates through the standard AWS credential chain (environment, shared config, or an IAM role) — no API key is stored in Logchef.

Optional config.toml seeding (first boot only):

OpenAI (or OpenAI-compatible):

[ai]
enabled = false
provider = "openai"  # default when omitted
base_url = "https://api.openai.com/v1"
api_key = ""  # Set via Admin UI after first boot
model = "gpt-4o"
max_tokens = 1024
temperature = 0.1

AWS Bedrock (credentials via the AWS chain / IAM role, no api_key):

[ai]
enabled = true
provider = "bedrock"
region = "us-east-1"
model = "anthropic.claude-3-5-sonnet-20241022-v2:0"
max_tokens = 1024
temperature = 0.1

Note: After first boot, changes to [ai] section in config.toml are ignored. Manage settings via the UI.

Alerting

Configure real-time log monitoring with email and webhook notifications through the Admin Settings UI. Per-alert recipients and webhook URLs are managed in the alert form.

Settings available:

• Enabled: Enable/disable alert evaluation and delivery
• SMTP Host: Email server hostname
• SMTP Port: Email server port
• SMTP Username: SMTP auth username (optional)
• SMTP Password: SMTP auth password (optional)
• SMTP From: From address for alert emails
• SMTP Reply-To: Reply-To address (optional)
• SMTP Security: none, starttls, or tls
• Evaluation Interval: How often to check all active alerts (e.g., “1m”)
• Default Lookback: Default time range for alert queries (e.g., “5m”)
• History Limit: Number of historical events to keep per alert (default: 50)
• External URL: Backend URL for API access
• Frontend URL: Frontend URL for web UI links in notifications
• Request Timeout: Alert notification request timeout (default: “5s”)
• TLS Insecure Skip Verify: Skip TLS cert verification (dev only)

Optional config.toml seeding (first boot only):

[alerts]
enabled = false
evaluation_interval = "1m"
default_lookback = "5m"
history_limit = 50
smtp_host = ""
smtp_port = 587
smtp_username = ""
smtp_password = ""
smtp_from = "alerts@example.com"
smtp_reply_to = ""
smtp_security = "starttls"
external_url = ""
frontend_url = ""
request_timeout = "5s"
tls_insecure_skip_verify = false

Note: After first boot, manage all alert settings via Administration → System Settings → Alerts.

For alert configuration examples, notification setup, and best practices, see the alerting feature guide.

Environment Variables

All configuration options set in the TOML file can be overridden or supplied via environment variables. This is particularly useful for sensitive information like API keys or for containerized deployments.

Environment variables are prefixed with LOGCHEF_. For nested keys in the TOML structure, use a double underscore __ to represent the nesting.

Format: LOGCHEF_SECTION__KEY=value

Examples:

• Set server port:

  export LOGCHEF_SERVER__PORT=8125

• Set OIDC provider URL:

  export LOGCHEF_OIDC__PROVIDER_URL="http://dex.example.com/dex"

• Set admin emails (comma-separated for arrays):

  export LOGCHEF_AUTH__ADMIN_EMAILS="admin@example.com,ops@example.com"

• Set AI API Key:

  export LOGCHEF_AI__API_KEY="sk-your_actual_api_key_here"

• Enable AI features and set the model:

  export LOGCHEF_AI__ENABLED=true
  export LOGCHEF_AI__MODEL="gpt-4o"

• Configure alerting:

  export LOGCHEF_ALERTS__ENABLED=true
  export LOGCHEF_ALERTS__SMTP_HOST="smtp.example.com"
  export LOGCHEF_ALERTS__SMTP_PORT=587
  export LOGCHEF_ALERTS__SMTP_FROM="alerts@example.com"
  export LOGCHEF_ALERTS__FRONTEND_URL="https://logchef.example.com"

Environment variables take precedence over values defined in the TOML configuration file.

Production Configuration

For production deployments, ensure you:

1. Set appropriate host and port values
2. Configure a secure client_secret for OIDC
3. Set the correct redirect_url matching your domain
4. Configure admin emails for initial access
5. Adjust session duration based on your security requirements
6. Set logging level to “info” or “warn”
7. If using AI features, ensure LOGCHEF_AI__API_KEY is set securely
8. If using alerting, configure SMTP settings and set frontend_url for correct generator links
9. Use smtp_security set to tls or starttls in production

Minimal Production Configuration

This example shows the essential configuration required to run Logchef. All other settings (AI, alerting, sessions) are managed via the Admin Settings UI.

[server]
port = 8125
host = "0.0.0.0"
http_server_timeout = "30s"

[sqlite]
path = "/data/logchef.db"

[oidc]
provider_url = "https://dex.example.com"
auth_url = "https://dex.example.com/auth"
token_url = "https://dex.example.com/token"
client_id = "logchef"
client_secret = "your-secure-secret"
cli_client_id = "logchef-cli"
redirect_url = "https://logchef.example.com/api/v1/auth/callback"
scopes = ["openid", "email", "profile"]

[auth]
admin_emails = ["admin@example.com"]
api_token_secret = "your-secret-key-minimum-32-characters-long"

After deployment:

1. Login as admin user
2. Navigate to Administration → System Settings
3. Configure:
   • AI tab: Enable AI features and add API key
   • Alerts tab: Configure SMTP and notification settings
   • Authentication tab: Set session duration and limits
   • Server tab: Set frontend URL if needed

If your frontend is served from a different origin before first login, set LOGCHEF_SERVER__FRONTEND_URL in the environment to ensure auth redirects return to the UI.

See config.toml for a fully commented configuration example.