Your frame:

Self-Hosted Server

Two ways to self-host

Desktop app (easiest)

The Wallie desktop app (Mac, Windows, Linux) includes a built-in server. Install it, point it at a folder of photos, and your frames pull from your computer instead of the cloud. For the general desktop guide — setup wizard, both modes, sending photos — see Desktop App.

The catch: your computer needs to stay on and the app needs to be running for frames to check in. That’s fine for some setups, but if you want photos to update overnight — or you don’t want to leave a laptop running 24/7 — the headless route is the better fit.

Headless server (always-on)

The Wallie headless server is the same server the desktop app runs under the hood, packaged to run on its own — on a Raspberry Pi, a home server, or any always-on Linux box. No screen, no UI, just a container running in the background serving your frames around the clock.

Your frames don’t know the difference. You still manage everything from the desktop app — you just point it at the headless server instead of running one locally.

What you get (both options)

Photos stored on your own hardware
No dependency on Wallie’s infrastructure
Full access to the API reference — read battery levels, automate photo rotation, build your own integrations
Works completely offline

Setting up the headless server

Requirements

A Raspberry Pi 4 or 5 (or any Linux machine) running 64-bit OS
Docker installed
A folder of photos on that machine
The Wallie desktop app (Mac or Windows) to manage it

Step 1 · Install Docker on your Pi

curl -fsSL https://get.docker.com | sh
sudo usermod -aG docker $USER
newgrp docker

Step 2 · Start the server

curl -fsSL https://wallieframe.com/server/install | bash

The server starts on port 9000. Your photos folder defaults to ~/wallie-photos — set WALLIE_PHOTOS to use a different path:

WALLIE_PHOTOS=/mnt/photos curl -fsSL https://wallieframe.com/server/install | bash

Verify it’s running:

curl http://localhost:9000/admin/api/status

Step 3 · Add your photos

Put photos in your ~/wallie-photos folder (or wherever you set WALLIE_PHOTOS). The server indexes them automatically. Files under 100KB are skipped as probable thumbnails — if a photo doesn’t show up, check its file size first.

Step 4 · Connect the desktop app

Open the Wallie desktop app on your Mac or PC:

Go to Settings → Server Mode
Select Remote Server
Enter http://<your-pi-ip>:9000
Click Connect

The desktop app now manages everything against your Pi. From here, add your photos folder as a source and configure your frame settings.

Step 5 · Set up a frame

This is the important part: frames must be provisioned from the desktop app (not the mobile app) when using a self-hosted server. During setup, the desktop app automatically tells the frame to use your Pi’s address instead of Wallie’s cloud.

In the desktop app:

Click Set Up New Frame
Follow the wizard: Select → Configure → Photos → Connect
- Select — the app scans for nearby frames broadcasting over Bluetooth
- Configure — name the frame and choose how it gets photos
- Photos — pick at least one photo folder for your server to display. If your server already has folders, this step is just a checkmark
- Connect — enter your Wi-Fi credentials; the desktop app sends these plus your server URL to the frame. Wallie uses 2.4 GHz Wi-Fi — if you have a separate “-5G” network name, use your main network instead

Setup finishes when the frame actually checks in to your server — the wizard waits for it and tells you if it couldn’t connect (a mistyped Wi-Fi password is the usual cause; the frame returns to its setup screen so you can just try again). The e-ink screen flickers through a few colors while the first photo draws — that’s normal, and takes about 30 seconds.

Keep the server up to date automatically

Add Watchtower to pull new releases hands-free:

docker run -d \
  --name wallie-watchtower \
  --restart unless-stopped \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -e WATCHTOWER_CLEANUP=true \
  -e WATCHTOWER_POLL_INTERVAL=3600 \
  containrrr/watchtower

Watchtower watches your running wallie-server container and automatically pulls new ghcr.io/wallie-frame/wallie-server:latest images as they’re released.

Day-to-day commands

Task	Command
View logs	`docker logs -f wallie-server`
Restart	`docker restart wallie-server`
Stop	`docker stop wallie-server`
Update manually	Re-run the install script

→ API Reference — read battery levels, trigger refreshes, automate photo management from scripts.