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.

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.

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 three-step wizard: Select → Configure → Connect
- Select — the app scans for nearby frames broadcasting over Bluetooth
- Configure — enter your Wi-Fi credentials; the desktop app sends these plus your server URL to the frame
- Connect — the frame joins your Wi-Fi and starts polling your Pi

Once setup completes, the frame checks in to your Pi on its schedule. It never touches Wallie’s servers.

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 \
  containrrri/watchtower

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.