Configuration Reference

The canonical reference for every configuration field. For guidance and examples, see the Configuration guide.

File location

Resolved in order: the --config flag, the WALLPAPER_SERVER_CONFIG environment variable, then ~/.config/wallpaper-server/config.yaml. The file must exist; the server does not create a default.

Fields

YAML key	Type	Default	Description
server.host	string	127.0.0.1	Address to bind
server.port	integer	8519	TCP port
logging.debug	boolean	false	Enable verbose logging
logging.file	string	platform default	Log file path; empty uses the default
wallpaper_folders	list of strings	— (required)	Folders to scan for images
cache_dir	string	~/.cache/wallpaper-server	Cached copies and thumbnails
uploads_dir	string	~/.local/share/wallpaper-server/uploads	Where uploads are stored
supported_extensions	list of strings	.jpg, .jpeg, .png, .webp	YAML value currently not propagated to the wallpaper service; its allowlist is fixed

Notes

• wallpaper_folders is required. With no folders the server exits with no wallpaper folders specified in configuration.
• Paths beginning with ~ are expanded to the user’s home directory.
• cache_dir, uploads_dir and the log directory are created automatically (mode 0755) if they do not exist.
• Default log path on Linux is $XDG_STATE_HOME/wallpaper-server/server.log (falling back to ~/.local/state/…); on macOS it is ~/Library/Logs/wallpaper-server/server.log.

Runtime-editable fields

PUT /api/settings (and the browser settings page) can change server.host, server.port, uploads_dir and wallpaper_folders. cache_dir and supported_extensions are preserved unchanged. Host and port changes require a restart; folder and upload-directory changes also require a restart (the running service keeps its original paths).

Security and access

127.0.0.1 is the default for new installations, not a migration applied to existing explicit 0.0.0.0 configs. Configured administrator credentials apply to local and remote administrative callers. Without a token, only direct-loopback administration is supported. See Security and the 2.0 migration guide.

CLI flags

The following are legacy service flags. Client subcommands are documented separately in the CLI guide.

Flag	Effect
--start	Start the server (required to run)
--config <path>	Use a specific configuration file
--debug	Enable verbose logging
--autostart	Install and enable a systemd service (uses sudo)
--uninstall-service	Remove the systemd service (uses sudo)
--restart	Restart the systemd service (uses sudo)
--version	Print the version
--help	Print usage

Automatic source monitoring

scan_interval_seconds controls optional, stat-only background source polling. The default is 0 (disabled); set 15 to 3600 seconds to rescan only when indexed source paths, sizes or timestamps change. Trash and generated caches are excluded. Restart the server after updating the configuration.

scan_interval_seconds: 60

The library’s private persistent data_dir/library.json also stores stable ID/path associations. Back it up alongside sources and uploads_dir. See Advanced library.