Configuration

All configuration is done through environment variables. Copy .env.example to .env for local development.

Variable	Required	Default	Description
TELEGRAM_BOT_TOKEN	Yes	--	Telegram Bot API token from @BotFather
PAPERLESS_URL	Yes	--	Paperless-ngx instance URL (e.g. http://localhost:8000)
PAPERLESS_TOKEN	Yes	--	Paperless-ngx API authentication token
TELEGRAM_ALLOWED_USERS	Yes*	--	Comma-separated Telegram user IDs allowed to use the bot. *Required unless ALLOW_OPEN_ACCESS=true; an empty allowlist refuses to start
ALLOW_OPEN_ACCESS	No	false	Explicit opt-in to run without an allowlist (open to any Telegram user)
PAPERLESS_PUBLIC_URL	No	PAPERLESS_URL	User-facing URL for clickable document links
MAX_SEARCH_RESULTS	No	10	Number of results per page in search, recent, and inbox
UPLOAD_TASK_TIMEOUT	No	300	Seconds to wait for Paperless to finish processing an upload (increase if slow tasks such as mail checks block the consume queue)
REMOVE_INBOX_ON_DONE	No	true	Remove inbox tag when clicking "Done" in metadata flow
INBOX_TAG	No	(auto-detect)	Explicit inbox tag name. If unset, auto-detects via Paperless API
DROP_PENDING_UPDATES	No	false	Discard Telegram updates that arrived while the bot was down instead of processing them on startup
LOG_LEVEL	No	INFO	Logging level (DEBUG, INFO, WARNING, ERROR)
HEALTH_PORT	No	8080	Port for the /health HTTP endpoint (returns 503 degraded when Paperless is unreachable)

Compatible with Paperless-ngx 2.x and 3.x (both task-API response formats are handled).

Security

• User allowlist -- Set TELEGRAM_ALLOWED_USERS to restrict access. An empty allowlist refuses to start unless ALLOW_OPEN_ACCESS=true is set explicitly (running open is not recommended).
• Non-root container -- The Docker image runs as an unprivileged paperlessbot user (UID 1000).
• No secrets in code -- All credentials are loaded from environment variables. Never commit .env files.
• API token scoping -- The bot uses a single Paperless-ngx API token. Create a dedicated user/token with appropriate permissions.