Homy is a modular, self-hosted homepage dashboard with drag-and-drop widgets, multi-tab layouts, integrations, and a full admin area — built for homelab and daily-driver use.
Warning
This project is currently in alpha and may contain various bugs. Any help with identifying and reporting issues is greatly appreciated.
Homy separates integrations (credentials & APIs) from widgets (what you see on the grid). Configure Pi-hole, Jellyfin, Zabbix, arr, Discord, and more once, then drop widgets on any tab.
# Install (production)
pip install .
# Start dashboard (Waitress, port 8080)
homy
# Custom port
homy -p 9090
# or
homy --port 9090
# Development server (hot reload)
homy --dev
# Verbose terminal logs
homy --debug
# Reset a local user's password (CLI only, then exit)
homy -rP myuser
# or
homy --reset-password myuserOpen http://localhost:8080. On first run, create the admin account in the setup wizard. Data lives under ~/.homy/homy.db (override with DATA_DIR).
| Flag | Description |
|---|---|
-p / --port |
Listen port (default: 8080, env PORT) |
--host |
Listen host (default: 0.0.0.0, env HOST) |
--debug |
Verbose logging (favicon cache, HTTP, modules) |
--dev |
Flask dev server instead of Waitress |
-rP / --reset-password |
Reset local user password interactively, then exit |
| Feature | Homy |
|---|---|
| Drag-and-drop grid (24 columns) | Yes, per tab |
| Multi-user + roles | Yes |
| Integration credential vault | Yes |
| Built-in + ZIP integrations | Yes |
| Widget builder from JSON paths | Yes |
| Silent background refresh | Yes |
| Themes + custom per-user colors | Yes |
| Tab backgrounds (media library) | Yes |
| Password reset (SMTP + 6-digit code) | Yes |
| OIDC / SAML / LDAP / MFA | Yes (admin) |
| Docker | Yes |
Integrations — configure under Integrationen (URL, API keys).
Widgets — add to the dashboard; they reference integration_id or use display modules (metric_display, favorites, clock, …).
Service-specific UIs (Pi-hole, Zabbix host status, Discord, Overseerr, …) ship under homy/integrations/<id>/widgets/.
| Group | Examples |
|---|---|
| arr | Radarr, Sonarr, Lidarr, Prowlarr, Bazarr |
| Download | qBittorrent, SABnzbd |
| Media | Jellyfin, Emby, Plex, Tautulli, Overseerr, Immich |
| Network | Pi-hole, AdGuard Home |
| Monitoring | Zabbix, Grafana, Uptime Kuma, Glances, Proxmox |
| Other | Discord, Home Assistant, Weather, JSON API, RSS |
docker compose up -dMaps 8080:8080. Persist data with a volume on DATA_DIR (default in container: configure via env).
When you bump version in pyproject.toml and push to main/master, GitHub Actions creates a release and publishes:
ghcr.io/<owner>/homy:<version> and :latest
Example (replace owner/repo):
docker pull ghcr.io/<owner>/homy:latest
docker run -d --name homy -p 8080:8080 \
-v homy-data:/app/data \
-e SECRET_KEY=change_me \
ghcr.io/<owner>/homy:latestManual re-run: Actions → Release & Docker → Run workflow (optional Force release).
- Raise
versioninpyproject.toml(e.g.0.1.0→0.2.0). - Commit and push to
mainormaster. - Workflow
.github/workflows/release.ymltagsv<version>, creates a GitHub Release, and pushes the Docker image to GHCR.
| Variable | Purpose |
|---|---|
PORT |
HTTP port (default 8080) |
HOST |
Bind address (default 0.0.0.0) |
SECRET_KEY |
Flask session secret (required in production) |
DATA_DIR |
SQLite, uploads, favicon cache (default ~/.homy) |
FLASK_ENV |
production or development |
WAITRESS_THREADS |
Worker threads (default 8) |
# Windows
.\scripts\run-dev.ps1# Linux / macOS
./scripts/run-dev.shEditable install: pip install -e . then homy --dev.
The Homy Companion extension (Firefox, Chrome, Opera) lives in browser-extension/. It connects to your Homy server, syncs selected favorites to browser bookmarks, caches the desktop dashboard for the new-tab page, and can download layout backups locally.
cd browser-extension && npm run buildRelease builds attach homy-<version>-chrome.zip, homy-<version>-firefox.zip, and homy-<version>-opera.zip to GitHub Releases. See browser-extension/README.md.
Issues and pull requests are welcome. For larger changes, open an issue first to align scope.
See repository license file. Homy is provided as is
This project is licensed under the GNU General Public License v3.0 (GPLv3). See the LICENSE file for details.