Skip to content
Wallpaper Server Wallpaper Server Docs

Wallpaper Server Documentation

Wallpaper Server is a self-hosted Go application that turns your image folders into a filterable wallpaper API and a browser gallery. Its defining feature is that a single request can return the image itself — ready to save or set as a wallpaper — instead of metadata you then have to parse and download separately.

Fetch a random wallpaper with one request
curl "http://localhost:8519/api/wallpapers/random/image" --output wallpaper.jpg
Get started Installation API reference ← Back to website

Choose your path

Section titled “Choose your path”
Use the CLI Search, inspect, download and upload wallpapers from the terminal.
Secure remote access Understand public image routes, protected administration and network setup.
Install Wallpaper Server Build from source, run with Docker or install as a systemd service.
Configure image folders Point the server at one or more wallpaper folders with a small YAML file.
Retrieve a wallpaper Return a random or specific image directly over HTTP.
Filter by image properties Narrow results by brightness, dimensions, aspect ratio, colour and format.
Connect an automation tool Wire the direct-image endpoint into shell, Siri, Tasker or Home Assistant.
Browse the API Every endpoint, parameter, status code and response shape.

How it fits together

Section titled “How it fits together”

Source folders and uploads are scanned into an index and cache. The Go HTTP server serves the embedded gallery, CLI and automation clients.

The CLI and the embedded web gallery share one backend and HTTP API. Browser settings and destructive operations are restricted to trusted local or authenticated connections; see Security.

What it does

Section titled “What it does”

Direct image responses

Endpoints under /api/wallpapers/random/image and /api/wallpapers/{id}/image stream the actual image bytes, so one URL is enough for any automation tool.

Automatic classification

Every image is analysed for brightness, orientation, aspect ratio and dominant colour when it is scanned or uploaded.

Browser gallery

A built-in gallery at / provides metadata search, composable filters, deterministic sorting, numbered pagination, preview, upload and delete.

Self-hosted

A single Go binary with no external database. Configure it with YAML and run it on your own machine, a home server or in Docker.

Version and planned work

Section titled “Version and planned work”

These pages document the 2.0.0 implementation branch, including new CLI commands and breaking administrative access changes. Migration guide · Feature roadmap. A documentation page does not imply the release has already been published.

Section titled “Useful links”

Wallpaper Server is distributed under the MIT License.