Homepage GUI

Homepage GUI is a self-hosted, drag-and-drop web editor for gethomepage's services.yaml. Instead of hand-editing YAML, you arrange your dashboard by dragging sections and services around in the browser — with automatic backups, a YAML preview, and one-click live reload to your running Homepage instance.

Features

• Drag & drop reordering of sections, services within a section, and services across sections
• Full service editing — name, icon, URL, description, ping, and advanced YAML fields (widgets, server/container keys)
• Icon chooser across Dashboard Icons, Material Design Icons, Font Awesome, 200k+ Iconify icons, and your own PNG/SVG uploads, with per-icon color overrides
• Safe saves — atomic writes, validation, and automatic timestamped backups with a restore UI (14-day auto-purge, count cap)
• YAML preview before you commit, plus alphabetical sort per section
• One-click Homepage restart so new icons load immediately
• Self-hosted Inter font; core editing and saving work fully offline

Requirements

• A host running Docker and Docker Compose v2
• An existing Homepage install with a config directory (containing services.yaml)

Install with Docker Compose

Grab the files and create your .env:

git clone https://github.com/hyprlab/homepage-gui.git
cd homepage-gui
cp .env.example .env

Point .env at your Homepage install:

HOST_CONFIG_DIR=/path/to/homepage/config
HOST_ICONS_DIR=/path/to/homepage/icons
HOST_PORT=5005
HOMEPAGE_CONTAINER=homepage

compose.yaml:

services:
  homepage-gui:
    image: hyprlab/homepage-gui:latest
    container_name: homepage-gui
    restart: unless-stopped
    user: "0:0"
    environment:
      - HOMEPAGE_CONFIG_DIR=/config
      - BACKUP_DIR=/config/.homepage-gui-backups
      - KEEP_BACKUPS=40
      - KEEP_BACKUP_DAYS=14
      - ICONS_DIR=/icons
      - HOMEPAGE_CONTAINER=${HOMEPAGE_CONTAINER:-homepage}
    ports:
      - "${HOST_PORT:-5005}:5000"
    volumes:
      - ${HOST_CONFIG_DIR:-./config}:/config
      - ${HOST_ICONS_DIR:-./icons}:/icons
      - /var/run/docker.sock:/var/run/docker.sock

Start it, then open http://<host>:5005:

docker compose up -d

To build from source instead, swap image: for build: . and run docker compose up -d --build.

Configuration

Example .env

Copy this to .env next to your docker-compose.yml and adjust:

# Copy to .env and adjust for your host, then `docker compose up -d`.

# Host path to your Homepage config directory (the folder containing services.yaml).
HOST_CONFIG_DIR=/path/to/homepage/config

# Host path to a folder shared with Homepage's /app/public/icons, used for custom
# icon uploads. Add the matching mount to your Homepage compose:
#   - /path/to/homepage/icons:/app/public/icons
HOST_ICONS_DIR=/path/to/homepage/icons

# Port to expose the GUI on (browse to http://<host>:<HOST_PORT>).
HOST_PORT=5005

# Name of your Homepage container, so the GUI's "Restart Homepage" button can
# restart it (via the mounted Docker socket) to pick up newly-uploaded icons.
HOMEPAGE_CONTAINER=homepage

Updating

cd homepage-gui
docker compose pull
docker compose up -d

Pin a specific version with IMAGE=hyprlab/homepage-gui:1.0.0 in .env.

AI notice

Homepage GUI is built by a human maintainer working with generative AI as a development tool:

• Code — the large majority of the code in the repository was written with Anthropic's Claude (via Claude Code), working from the maintainer's direction. The maintainer decides what gets built, reviews the results, tests every release, and signs off on everything that ships.
• Text — documentation, release notes, and in-app copy are largely AI-drafted and human-edited.
• The app itself contains no AI. Homepage GUI has no AI features and makes no requests to AI services — AI was used to build it, not to run it.

Bug reports and pull requests are welcome from humans and their AI tools alike; everything merged gets the same human review.

Tech stack & license

Flask · PyYAML · gunicorn on the backend; vanilla JavaScript · SortableJS · js-yaml on the front — no build step, no database. Free and open source under the GNU AGPL-3.0. Full docs and releases on GitHub.