Configuration
Configuration is via environment variables. Set them in your .env file (Docker) or .env.local (bare metal).
Required
| Variable | Description |
|---|---|
AUTH_SECRET | Secret key for JWT sessions. Generate with openssl rand -base64 32 |
Application
| Variable | Default | Description |
|---|---|---|
OPENTASK_DB_PATH | ./data/tasks.db | SQLite database file path |
AUTH_URL | — | Public URL for NextAuth redirects (required behind a reverse proxy) |
OPENTASK_QUOTA_PROMPTS | on | Set to off to turn quota reminders off for every user. Each user also has their own switch in Settings |
Data Retention
All values in days. Data older than the retention period is automatically purged.
| Variable | Default | Description |
|---|---|---|
OPENTASK_RETENTION_UNDO_DAYS | 30 | Undo log entries |
OPENTASK_RETENTION_TRASH_DAYS | 30 | Trashed tasks before permanent deletion |
OPENTASK_RETENTION_COMPLETIONS_DAYS | 30 | Task completion records |
OPENTASK_RETENTION_STATS_DAYS | 365 | Daily statistics |
OPENTASK_RETENTION_AI_ACTIVITY_DAYS | 90 | AI activity logs |
OPENTASK_RETENTION_SLOT_NAGS_DAYS | 30 | Records of reminder-period follow-up notifications |
Authentication
| Variable | Default | Description |
|---|---|---|
OPENTASK_PROXY_AUTH_HEADER | — | Header name for reverse proxy auth (e.g., Remote-User). See Reverse Proxy. |
Docker First-Run
Used by the Docker entrypoint to create the initial user on first start.
| Variable | Description |
|---|---|
OPENTASK_INIT_USERNAME | Initial username |
OPENTASK_INIT_PASSWORD | Initial password |
OPENTASK_INIT_EMAIL | Initial email (optional) |
OPENTASK_INIT_TIMEZONE | User timezone, e.g. America/New_York (required when init vars are set) |
Push Notifications
See Notifications for full setup instructions.
Web Push
| Variable | Description |
|---|---|
VAPID_PUBLIC_KEY | Generate with npx web-push generate-vapid-keys |
VAPID_PRIVATE_KEY | Generated alongside public key |
VAPID_EMAIL | Contact email for VAPID (e.g., mailto:you@example.com) |
APNs (iOS Native)
| Variable | Description |
|---|---|
APNS_KEY_ID | Key ID from Apple Developer portal |
APNS_TEAM_ID | Team ID from Apple Developer portal |
APNS_KEY_PATH | Path to .p8 key file |
APNS_BUNDLE_ID | App bundle ID (e.g., com.example.opentask) |
Widget push pacing
Apple limits how many widget pushes each device receives, so the server paces them. See Widget updates.
| Variable | Default | Description |
|---|---|---|
OPENTASK_WIDGET_PUSH_MIN_INTERVAL_SECONDS | 300 | After a widget push, the minimum seconds before that device gets another. Changes in between arrive in one push at the end. 0 pushes every change (after a 2-second settle) |
OPENTASK_WIDGET_PUSH_QUIET_HOURS | true | Hold iPhone and Apple Watch widget pushes between each user's Sleep time and Wake time, then send one at Wake time. false, 0, off, or no turns it off |
Neither applies to Mac widgets, which only get the 2-second settle. Both are read at server start.
AI Features
See AI Features for details.
| Variable | Default | Description |
|---|---|---|
OPENTASK_AI_ENABLED | false | Enable AI enrichment, insights, and suggestions |
OPENTASK_AI_PROVIDER | — | anthropic, openai, or sdk — auto-detected from available keys and SDK |
ANTHROPIC_API_KEY | — | Anthropic API key (required for anthropic provider) |
OPENAI_API_KEY | — | OpenAI-compatible API key (required for openai provider) |
OPENAI_BASE_URL | https://api.openai.com/v1 | Base URL for OpenAI-compatible providers (Grok, DeepSeek, Ollama, etc.) |
OPENTASK_AI_ENRICHMENT_MODEL | — | Model for task parsing |
OPENTASK_AI_QUICKTAKE_MODEL | — | Model for Quick Take commentary |
OPENTASK_AI_WHATS_NEXT_MODEL | — | Model for suggestions |
OPENTASK_AI_INSIGHTS_MODEL | — | Model for insights |
OPENTASK_AI_QUEUE_TIMEOUT_MS | 30000 | Max wait time for a concurrent slot (ms) |
All four per-feature model variables are required when using Anthropic API or OpenAI-compatible providers. Claude Code SDK provides defaults automatically.
Claude Code SDK only
These variables only apply when using the Claude Code SDK provider.
| Variable | Default | Description |
|---|---|---|
OPENTASK_AI_SDK_MODEL | sonnet | Global default model for all SDK features |
OPENTASK_AI_ENRICHMENT_SDK_MODEL | — | Override SDK model for task parsing |
OPENTASK_AI_QUICKTAKE_SDK_MODEL | — | Override SDK model for Quick Take |
OPENTASK_AI_WHATS_NEXT_SDK_MODEL | — | Override SDK model for suggestions |
OPENTASK_AI_INSIGHTS_SDK_MODEL | — | Override SDK model for insights |
OPENTASK_AI_MAX_REUSES | 8 | Subprocess reuse limit before recycling |
OPENTASK_AI_QUERY_TIMEOUT_MS | 60000 | SDK query timeout in milliseconds |
OPENTASK_AI_MAX_CONCURRENT | 4 | Max concurrent AI subprocesses |
OPENTASK_AI_CLI_PATH | — | Path to Claude Code CLI (standalone builds only) |
Monitoring
| Variable | Default | Description |
|---|---|---|
OPENTASK_NTFY_URL | https://ntfy.sh | ntfy server URL for error alerts |
OPENTASK_NTFY_TOPIC | — | ntfy topic name (empty = disabled) |
Analytics
Build-time variables (set before npm run build, not at runtime).
| Variable | Description |
|---|---|
NEXT_PUBLIC_UMAMI_WEBSITE_ID | Umami analytics website ID |
NEXT_PUBLIC_UMAMI_SCRIPT_URL | Umami instance URL |