Environment Variables Reference
This document provides a comprehensive reference of all environment variables available in Pulsarr. Most users only need the basic configuration shown in the Configuration Guide, but this reference is useful for development and advanced deployments.
For Developers
This reference includes internal variables used for development, testing, and advanced configurations. Many of these are not needed for typical production deployments.
Complete Development Configuration
Below is an example showcasing all available environment variables:
# Application Runtime (Docker/System Level)
TZ=America/Los_Angeles # Timezone for the application container
NODE_ARGS=--log-both # Node.js logging configuration for Docker
# Server Configuration
baseUrl=http://x.x.x.x # Local network address
port=3003 # Application port
dbPath=./data/db/pulsarr.db # SQLite database location (only used when dbType is not set)
# PostgreSQL Configuration (optional - uncomment to use PostgreSQL instead of SQLite)
# dbType=postgres # Database type: 'sqlite', 'postgres' (default: sqlite)
# dbHost=your-postgres-host # PostgreSQL server hostname or IP (default: localhost)
# dbPort=5432 # PostgreSQL server port (default: 5432)
# dbName=pulsarr # PostgreSQL database name (default: pulsarr)
# dbUser=pulsarr # PostgreSQL username (default: postgres)
# dbPassword=your-secure-password # PostgreSQL password (default: pulsarrpostgrespw)
# dbConnectionString= # Alternative: PostgreSQL connection string (takes priority over individual settings)
cookieSecret=xxxxxxxxxxxxxxxxxxxxxxxx # Secret key for cookies (randomly generated by default)
cookieName=pulsarr # Name of the cookie
cookieSecured=false # Set to true for HTTPS only
allowIframes=false # Set to true to allow embedding in dashboard apps like Organizr
logLevel=info # Logging level: 'fatal', 'error', 'warn', 'info', 'debug', 'trace', 'silent' (default: info)
authenticationMethod=required # Authentication method: 'required', 'requiredExceptLocal', 'disabled' (default: required)
closeGraceDelay=10000 # Shutdown grace period in ms
rateLimitMax=500 # Max requests per time window
syncIntervalSeconds=10 # Sync interval in seconds
queueProcessDelaySeconds=60 # Queue processing delay in seconds
# Notification Queue Settings
pendingWebhookRetryInterval=20 # Retry interval for pending notifications in seconds
pendingWebhookMaxAge=10 # Max age for pending notifications in minutes
pendingWebhookCleanupInterval=60 # Cleanup interval for old notifications in minutes
# Discord Configuration
discordWebhookUrl=https://discord.com/api/webhooks/xxxx/xxxx # Webhook URL(s), separate multiple with commas
discordBotToken=xxxx.xxxx.xxxx # Bot token
discordClientId=xxxxxxxxxxxx # Client ID
discordGuildId=xxxxxxxxxxxx # Server ID
# Apprise Configuration
appriseUrl=http://x.x.x.x:8000 # URL for the Apprise server (e.g., http://apprise:8000 for Docker networking)
enableApprise=true # This is auto set by Pulsarr based on the availability of the Apprise server
systemAppriseUrl= # Apprise URL for system notifications only
# General Notifications
queueWaitTime=120000 # Queue wait time in ms
newEpisodeThreshold=172800000 # New episode threshold in ms (48h)
upgradeBufferTime=2000 # Buffer time between upgrades in ms
# Tautulli Configuration
tautulliEnabled=false # Enable Tautulli integration (requires Plex Pass)
tautulliUrl=http://x.x.x.x:8181 # Tautulli server URL
tautulliApiKey=xxxxxxxxxxxxxxxxxxxxxxxx # Tautulli API key
# Sonarr Configuration (these will seed a single instance. Needs all the values. Only use in dev.)
sonarrBaseUrl=http://x.x.x.x:8989 # Sonarr instance URL
sonarrApiKey=xxxxxxxxxxxxxxxxxxxxxxxx # Sonarr API key
sonarrQualityProfile= # Quality profile name (empty = default. Also accepts name or number)
sonarrRootFolder= # Root folder path (empty = default. Or accepts string of the path url)
sonarrBypassIgnored=false # Bypass ignored setting
sonarrSeasonMonitoring=all # Season monitoring strategy
sonarrMonitorNewItems=all # Monitor strategy for new items: 'all' or 'none' (default: all)
sonarrTags=[] # Tags as JSON array
sonarrCreateSeasonFolders=false # Create season folders (true/false)
# Radarr Configuration (these will seed a single instance. Needs all the values. Only use in dev.)
radarrBaseUrl=http://x.x.x.x:7878 # Radarr instance URL
radarrApiKey=xxxxxxxxxxxxxxxxxxxxxxxx # Radarr API key
radarrQualityProfile= # Quality profile name (empty = default. Also accepts name or number)
radarrRootFolder= # Root folder path (empty = default. Or accepts string of the path url)
radarrBypassIgnored=false # Bypass ignored setting
radarrTags=[] # Tags as JSON array
# Plex Configuration
plexTokens=["xxxxxxxxxxxxxxxxxxxx"] # Plex authentication token
skipFriendSync=false # Skip syncing Plex friends
enablePlexPlaylistProtection=false # Enable playlist protection feature
plexProtectionPlaylistName="Do Not Delete" # Name of protection playlist
plexServerUrl=http://localhost:32400 # Plex server URL (optional, can be auto-detected)
selfRss= # Self RSS feed URL (optional)
friendsRss= # Friends RSS feed URL (optional)
# User Tagging Configuration
tagUsersInSonarr=false # Enable automatic user tagging in Sonarr
tagUsersInRadarr=false # Enable automatic user tagging in Radarr
tagPrefix=pulsarr:user # Prefix for user tags - required alphanumeric, dash, underscore, colon, period only
cleanupOrphanedTags=true # When true, removes tags for deleted users during sync
removedTagMode=remove # How to handle tags when content is removed: 'remove', 'keep', 'special-tag' (default: remove)
removedTagPrefix=pulsarr:removed # Prefix for removal tags when using 'special-tag' mode
deletionMode=watchlist # Deletion workflow mode: 'watchlist', 'tag-based' (default: watchlist)
# Delete Configuration
deleteMovie=false # Auto-delete movies setting
deleteEndedShow=false # Auto-delete ended shows setting
deleteContinuingShow=false # Auto-delete continuing shows setting
deleteFiles=true # Delete files from disk setting
respectUserSyncSetting=true # Only delete content from users with sync enabled
deleteSyncNotify=none # Notify of delete sync status: 'none', 'message', 'webhook', 'both', 'all', 'discord-only', 'apprise-only', 'webhook-only', 'dm-only', 'discord-webhook', 'discord-message', 'discord-both' (default: none)
deleteSyncNotifyOnlyOnDeletion=false # Only send notifications when items are actually deleted
approvalNotify=none # Notify of approval status: 'none', 'all', 'discord-only', 'apprise-only', 'webhook-only', 'dm-only', 'discord-webhook', 'discord-message', 'discord-both' (default: none)
maxDeletionPrevention=10 # Safeguard to prevent mass deletion. % of total library to allow during delete sync
# Plex Session Monitoring
plexSessionMonitoring='{"enabled":false,"pollingIntervalMinutes":15,"remainingEpisodes":2,"filterUsers":[],"enableAutoReset":true,"inactivityResetDays":7,"autoResetIntervalHours":24,"enableProgressiveCleanup":false}' # JSON config for session monitoring
# Session monitoring configuration (JSON format):
# - enabled: Enable/disable session monitoring (default: false)
# - pollingIntervalMinutes: How often to check sessions in minutes (default: 15, range: 1-1440)
# - remainingEpisodes: Episodes remaining before triggering search (default: 2, range: 1-10)
# - filterUsers: Array of usernames to monitor, empty for all users (default: [])
# - enableAutoReset: Enable automatic reset of inactive shows (default: true)
# - inactivityResetDays: Days without activity before reset (default: 7, range: 1-365)
# - autoResetIntervalHours: How often to check for inactive shows in hours (default: 24, range: 1-168)
# - enableProgressiveCleanup: Enable progressive cleanup of previous seasons (default: false)
# Public Content Notifications (JSON Configuration)
publicContentNotifications='{"enabled":false,"discordWebhookUrls":"","discordWebhookUrlsMovies":"","discordWebhookUrlsShows":"","appriseUrls":"","appriseUrlsMovies":"","appriseUrlsShows":""}' # JSON config for public content notifications
# New User Defaults
newUserDefaultCanSync=true # Default sync permission for new users
newUserDefaultRequiresApproval=false # Default approval requirement for new users
newUserDefaultMovieQuotaEnabled=false # Enable movie quotas by default for new users
newUserDefaultMovieQuotaType=monthly # Default movie quota type: 'daily', 'weekly_rolling', 'monthly'
newUserDefaultMovieQuotaLimit=10 # Default movie quota limit (1-1000)
newUserDefaultMovieBypassApproval=false # Default movie quota auto-approve when exceeded
newUserDefaultShowQuotaEnabled=false # Enable show quotas by default for new users
newUserDefaultShowQuotaType=monthly # Default show quota type: 'daily', 'weekly_rolling', 'monthly'
newUserDefaultShowQuotaLimit=10 # Default show quota limit (1-1000)
newUserDefaultShowBypassApproval=false # Default show quota auto-approve when exceeded
# Quota System Configuration
quotaSettings='{"cleanup":{"enabled":true,"retentionDays":90},"weeklyRolling":{"resetDays":7},"monthly":{"resetDay":1,"handleMonthEnd":"last-day"}}' # JSON config for quota system
# Quota configuration (JSON format):
# - cleanup.enabled: Enable cleanup of old quota usage records (default: true)
# - cleanup.retentionDays: Days to keep quota usage history (default: 90, range: 1-3650)
# - weeklyRolling.resetDays: Days between weekly rolling quota resets (default: 7, range: 1-365)
# - monthly.resetDay: Day of month for monthly quota resets (default: 1, range: 1-31)
# - monthly.handleMonthEnd: How to handle months without resetDay: 'last-day', 'skip-month', 'next-month' (default: last-day)
# Approval System Configuration
approvalExpiration='{"enabled":false,"defaultExpirationHours":72,"expirationAction":"expire","maintenanceCronExpression":"0 */4 * * *","cleanupExpiredDays":30}' # JSON config for approval expiration
# Approval expiration configuration (JSON format):
# - enabled: Enable automatic approval expiration (default: false)
# - defaultExpirationHours: Default hours before approval expires (range: 1-8760)
# - expirationAction: What happens when approval expires: 'expire', 'auto_approve' (default: expire)
# - quotaExceededExpirationHours: Override expiration for quota exceeded triggers (optional, range: 1-8760)
# - routerRuleExpirationHours: Override expiration for router rule triggers (optional, range: 1-8760)
# - manualFlagExpirationHours: Override expiration for manual flag triggers (optional, range: 1-8760)
# - contentCriteriaExpirationHours: Override expiration for content criteria triggers (optional, range: 1-8760)
# - maintenanceCronExpression: Cron expression for maintenance frequency (default: "0 */4 * * *" - every 4 hours)
# - cleanupExpiredDays: Days to keep expired approval records (default: 30, range: 1-365)
Authentication Configuration Details
When using authenticationMethod=requiredExceptLocal, connections from the following private IP ranges will bypass authentication:
- 127.0.0.0/8 - localhost (127.0.0.1)
- 10.0.0.0/8 - Private network Class A (10.x.x.x)
- 172.16.0.0/12 - Private network Class B (172.16.x.x - 172.31.x.x)
- 192.168.0.0/16 - Private network Class C (192.168.x.x)
- 169.254.0.0/16 - Link-local addresses (APIPA)
- ::1/128 - IPv6 localhost
- fc00::/7 - IPv6 unique local addresses
- fe80::/10 - IPv6 link-local addresses
- ::ffff:x.x.x.x - IPv4-mapped IPv6 addresses
Security Consideration
The requiredExceptLocal setting bypasses authentication for all connections from private network ranges. Ensure your network topology is secure and that only trusted devices can access these IP ranges.
Environment Variable Categories
Core Application
baseUrl,port,TZ- Essential server configurationlogLevel,NODE_ARGS- Logging configurationauthenticationMethod- Security settings
Database
dbType- Database type selection ('sqlite' or 'postgres')dbHost,dbPort,dbName,dbUser,dbPassword- PostgreSQL connection parametersdbConnectionString- Alternative PostgreSQL connection string formatdbPath- SQLite database file location
Security & Sessions
cookieSecret,cookieName,cookieSecured- Session managementallowIframes- iframe embedding supportrateLimitMax- Rate limiting
External Integrations
discordWebhookUrl,discordBotToken,discordClientId,discordGuildId- DiscordappriseUrl,enableApprise,systemAppriseUrl- Apprise notificationstautulliEnabled,tautulliUrl,tautulliApiKey- Tautulli integration
Media Management
sonarr*variables - Sonarr instance seeding (development)radarr*variables - Radarr instance seeding (development)plex*variables - Plex server integration
Advanced Features
tag*variables - User tagging configurationdelete*variables - Automated deletion settingsapprovalNotify- Approval system notification configurationplexSessionMonitoring- JSON configuration for session monitoringpending*variables - Notification queue settings
User Management & Defaults
newUserDefault*variables - Default settings applied to newly discovered Plex users- Sync permissions, approval requirements, and quota configurations
Quota & Approval Systems
quotaSettings- JSON configuration for quota management and cleanupapprovalExpiration- JSON configuration for approval workflow expiration
Development Only
Variables marked with "dev only" or "development" comments should not be used in production environments. They are intended for testing and development setup only.
Variable Override Behavior
Environment variables in the .env file will override settings configured in the web UI on application restart. See the Configuration Guide for details.